# Venues

Source: https://docs.settlemint.com/docs/console/asset-lifecycle/venues
Provision a venue, open its detail, list an instrument, pause the whole venue, and find the screen for each other venue task.

A venue is a deployed contract that lists one or more instruments, each a base and quote token pair with its own tick size, lot size, price bands and fee schedule. From **Venues** you provision a venue, list an instrument and pause the venue, and each venue tab holds one other task, from orders and desk limits to settlement and the trading calendar. [Trading](https://docs.settlemint.com/docs/console/my-assets/trading) is the investor and desk workspace for trading on an instrument that already exists.

Pausing or freezing a token, on [Emergency halt and freeze](https://docs.settlemint.com/docs/console/asset-management/manage/pause-freeze), acts on the token contract and reaches every venue. An instrument halt stops one instrument on this venue, as [Instrument](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/instrument) describes. Maker-checker is the two-operator pattern that desk limits and busts run on in the platform while the **Trading venues** approval row is on. On chain, the operations signer sends the approved bust.

![Detail page of the DALP Demo Exchange venue with the List instrument button and the Trading calendar tab](https://docs.settlemint.com/docs/screenshots/console-venue-operations.light.en.webp)

[Screenshot] The venue detail page with its header, its tabs and the "Overview" counts.

The header shows the venue name, the "Trading venue" label, the venue status badge and the "List instrument" button. Below it run the "Overview", "Desk administration", "Listing rules", "Permissions", "Trading calendar" and "Announcements" tabs, with the remaining tabs under "More". The "Overview" tab shows the "Instruments", "Open for trading", "Halted" and "Suspended" counts, the "Venue contract" address and a table of the venue's instruments.

## Before you start [#before-you-start]

- **An on-venue role for each action.** Inside a venue, the on-venue roles "Venue operator" and "Venue admin" gate individual actions, as [Which venue role each setting needs](#which-venue-role-each-setting-needs) lists.
- **A provisioned venue before the first listing.** The screen offers that step itself, as [Provision a venue](#provision-a-venue) describes.
- **The tokens and the parameters of the instrument.** Prepare the base and quote tokens, tick size, lot size, minimum notional, maker fees, taker fees, market-order protection band, and fee account before you list an instrument. The lot size must be exactly one whole base token, because the venue does not price fractional lots. The wizard holds the structure step until it reads the base token's decimals and offers "Try again" when that read fails, and the venue refuses any other lot size.
- **Which order types the instrument allows.** A trader can place a stop order only where the instrument allows Stop, and the venue holds the stop's balance from the moment it is placed.
- **The matching mode and visibility settled.** Those cannot change afterwards, so settle them first.
- **A second operator, when the venue asks for one.** While the venue's "Trading venues" row under "Approvals" on [General](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals) is on, approving a proposal needs a second operator distinct from whoever proposed it.

## Steps [#steps]

### Provision a venue [#provision-a-venue]

Open "Asset lifecycle", then **Venues**. The list shows, each in its own column, a venue's instrument count and its instruments open for trading, halted and suspended.

Select **Provision venue**, or "Provision the first venue" when the list is empty. Both appear for organisation owners and platform administrators. The "Provision a trading venue" flow asks you to name the venue and confirm with your wallet. Provisioning deploys the venue from your system's Trading Venue factory.

The wallet you confirm with becomes the venue's "Venue admin" and holds the default administrator role on its access manager, which sets any approval rule on the venue's checked functions. The organisation's managed operations signer, the platform's signing service, receives the venue submitter role, which submits settlement and busts. Once provisioning completes, select **List first instrument**.

The platform cannot propose or approve on chain, so a venue with an approval rule on listing an instrument, changing a fee schedule or changing a holding period refuses that change in the Console and the Platform API with "The venue requires on-chain approval for this action" (409, `VENUE_ONCHAIN_APPROVAL_REQUIRED`) and sends no transaction. To allow the change again, the venue's default admin sets the rule's approval count to 0.

### Open the venue [#open-the-venue]

Select a venue in the list to open its detail page. The **Overview** tab counts the venue's instruments, those open for trading, those halted and those suspended, and lists every instrument with its status, matching mode and price band. Select an instrument row to open [the instrument](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/instrument).

### Find the screen for your task [#find-the-screen-for-your-task]

| Task | Screen |
| --- | --- |
| Review, export and cancel orders | [Orders](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/orders) |
| Decide a mass cancel and download its record | [Mass cancellations](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/mass-cancellations) |
| Halt, suspend, delist, price bands, fees, calendar override | [Instrument](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/instrument) |
| Propose a desk limit, decide a venue configuration change | [Desk administration](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/desk-administration) |
| Set the defaults, order rule limits, starting values, admission minimums and retention | [Listing rules](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/listing-rules) |
| Admission, venue roles, blocks | [Permissions](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/permissions) |
| See why one wallet can or cannot trade | [Participant access](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/participant-access) |
| Hours, half days and closed days | [Trading calendar](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/trading-calendar) |
| Publish a notice | [Announcements](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/announcements) |
| Choose default email alerts | [Participant alerts](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/participant-alerts) |
| Undo a trade | [Trade busts](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/trade-busts) |
| Read what each settlement moves | [Settlement instructions](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/settlement-instructions) |
| Retry or bust a held fill | [Held fills](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/held-fills) |
| Keep records out of retention | [Legal holds](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/legal-holds) |
| Read trades and instrument status across venues | [Read the venues insights](#read-the-venues-insights) |

## List an instrument [#list-an-instrument]

Select **List instrument** in the venue header to configure the pair, the grid of tick size and lot size, the fees and the protection band. Review [which choices stay editable](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/instrument#most-listing-choices-get-a-later-edit-some-do-not) before you submit the listing request.

The listing signer must hold the venue operator role, and the organisation's operations signer must hold the venue submitter role. Both tokens settle through the venue's escrow, so listing needs no token feature and no authorisation from the token's issuer. The escrow sits on the system's compliance bypass list, so the token's compliance rules do not refuse a deposit into it. A missing prerequisite refuses the listing and identifies the step and account to fix. When the venue contract itself refuses the listing, the API answers [DALP-14003](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#domain-rule-errors) and names the venue's revert in `data.errorName` and `data.selector`. A fee above 1000 basis points, a zero tick size, a zero address, a pair already listed or permanently closed, and a paused venue each get their own reason and fix.

On the review chapter, **Checks before signing** also asks the platform whether it would accept the listing as entered. It runs once every other check has passed. A refusal, for example a listing the venue's listing rules do not admit or a pair that is already listed, shows as a blocked check with its reason and fix, and signing stays off, so you learn it before the PIN. The check stores nothing and signs nothing. The platform checks again when you sign, because the venue can change in between. If the check cannot answer, it does not block you and the listing request returns its own refusal.

The listing wizard starts from the venue's **Starting values for new instruments**, and the venue's "Order rule limits" cap the order types and time in force the new instrument can accept. A venue admin sets both on [Listing rules](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/listing-rules).

## Pause or resume the venue [#pause-or-resume-the-venue]

The venue's state, "Venue accepting orders" or "Venue paused", sits next to its name on every tab. To stop the whole venue, select **Pause venue** in the header. On a phone it sits in the more-actions menu. A venue operator or venue admin can pause it after wallet verification. While the venue's "Trading venues" approval row is on, the pause waits under "Venue configuration approvals" on [Desk administration](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/desk-administration#approve-or-reject-a-venue-configuration-change) until a different operator approves it, and a resume until a different venue admin approves it. Once it applies, the venue refuses new orders with the reason `venue-paused`, stops opening sessions, and stops new settlement batches. Due deliveries, cancels and payouts of free balances continue. The order ticket in the Console and in the Investor portal disables its place button and shows the pause reason beside it. An open trading desk picks up a pause or a resume without a reload. Existing orders stay on the book. Only a venue admin can select "Resume venue". Resuming the venue does not resume an instrument that was halted separately. Pause the venue for a venue-wide incident, and halt one instrument when only that instrument must stop.

## Read the venues insights [#read-the-venues-insights]

The **Insights** tab beside "All venues" shows how the venues trade, which instruments are live or halted, and where the venues are registered. Its range and comparison controls work as on [asset Insights](https://docs.settlemint.com/docs/console/asset-management/insights#open-insights-and-choose-the-period).

- **Key figures.** "Trades" counts trades across all venues in the range, with the trades of the last 24 hours. "Live instruments" shows the instruments open for trading now out of all listed, with how many are halted. "Venues" counts the venues, with how many have a live instrument. "Instruments traded in 24 hours" counts the instruments with at least one trade in that time, out of all listed.
- **Needs attention.** Cards count "Instruments halted", "Live instruments without trades in 24 hours" and "Instruments pending listing".
- **Composition and trend.** "Instruments by trades in 24 hours" and "Instruments by status" break the instruments down, "Trades" charts the trades over the range, and a map shows where the venues are registered.

## Which venue role each setting needs [#which-venue-role-each-setting-needs]

| Setting | Role |
| --- | --- |
| Pause the venue | Venue operator or venue admin |
| Resume the venue | Venue admin |
| Trading calendar and its closures, listing rules, default price band, VAT policy, retention policy, instrument groups | Venue admin |
| Fee tiers, a security's nationality list | Venue operator or venue admin |
| Decide a venue configuration approval | The role the change names |

The role must sit on one of your wallets. Without it, the control is disabled with a line that names the role it needs, or the wallet of yours that holds it, and the API refuses the request with `VENUE_ROLE_REQUIRED` before it asks for your wallet verification, so nothing is submitted.

## You should see [#you-should-see]

- Return to **Venues** and confirm that the instrument count includes the new listing.
- Open the venue: the new instrument shows on "Overview" with its status and matching mode.
- After a pause, the header reads "Venue paused" and the order ticket is disabled.
- After a resume, it reads "Venue accepting orders".

## Troubleshooting [#troubleshooting]

**There is no List instrument button**

Either the venue does not exist yet or your session cannot list instruments. The Console shows **List instrument**
only to organisation owners and platform administrators, and only once your organisation has provisioned a venue,
because a listing with no venue behind it cannot succeed. Select "Provision the first venue" on the Venues list: name
the venue and confirm with your wallet, and it deploys from the Trading Venue factory registered in your system. If
the venue already exists, ask an organisation owner or a platform administrator to list the instrument. If the
platform reports that the factory itself is not available, the system deployment's add-on registration has not
finished indexing, or the trading-venue add-on was never installed. The [error
catalogue](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference) describes both refusals.

## API routes [#api-routes]

### Surveillance reports [#surveillance-reports]

The FIX drop copy, its replay and the daily surveillance files have no Console screen. A venue operator or venue admin reads them through the venue reports routes, and each route needs one of those roles on that venue.

| Task | Route |
| --- | --- |
| Preview a trading day's reports before a resend | `GET /api/v2/addons/trading-venues/{venueAddress}/reports/{tradingDay}/replay` |
| Ask the session to resend a completed day, with wallet verification | `POST /api/v2/addons/trading-venues/{venueAddress}/reports/{tradingDay}/replay-requests` |
| List the day's surveillance files, or what blocks them | `GET /api/v2/addons/trading-venues/{venueAddress}/reports/{tradingDay}/files?format=valcsv` or `format=olc` |
| Download one file | `GET /api/v2/addons/trading-venues/{venueAddress}/reports/{tradingDay}/files/{fileName}` |

A venue the drop-copy settings do not name, or a session that is not enabled, answers a replay call with 409 and DALP-14389, and so does a replay request for a day that has not ended. The preview answers for a running day. A file call answers the same 409 when the drop-copy settings do not name the venue or lack an exchange OMS name. A file name the day does not produce answers 404 with DALP-14390. [Controls and evidence](https://docs.settlemint.com/docs/concepts/issuing-and-markets/trading-venue#controls-and-evidence) explains the session, each report and each file column.