# Venue journey

Source: https://docs.settlemint.com/docs/concepts/issuing-and-markets/venue-journey
Follow one security from listing on the trading venue through the identity check, funding, trading, settlement, positions, reports, and the session close.

This page follows one security through its whole life on a trading venue, in the order a real participant meets it: an operator lists an instrument, an investor passes identity checks, funds a wallet, places an order, and the platform matches it and settles it. It ends with the positions, statements, and shareholder lists that record the result. Step 1 can happen before, during, or after steps 2 to 4, but steps 2 to 4 run in order, and steps 5 to 7 run on every order. Each step names the screen where a person does the work and the Platform API route behind it. Use it to see how the other pages fit together. It does not replace them, and each step links to the page that holds the detail.

A trading venue is the contract and the services around it that run one or more instruments. An instrument is one trading line: a base token that is bought and sold, and a quote token that pays for it. [Venue operations](https://docs.settlemint.com/docs/console/asset-lifecycle/venues) covers the operator side, and [Trading](https://docs.settlemint.com/docs/console/my-assets/trading) covers the order ticket in detail. The [Trading Venue](https://docs.settlemint.com/docs/concepts/issuing-and-markets/trading-venue) concept explains why the design looks the way it does.

[Figure] The venue journey in eight steps, from listing to positions and reports. Step 1: an operator lists the instrument. Step 2: the investor completes identity checks on the Profile page. Step 3: the eligibility claim reaches the chain after an approved provider verdict or from a trusted issuer. Step 4: the investor funds a wallet with the quote token. Step 5: the investor signs and places an order in the Investor portal. Step 6: the venue matches orders by price, then by time. Step 7: fills settle on chain in batches, and each fill moves both legs together or fails as a whole. Step 8: positions, statements, and shareholder lists record the result. Labels: Venue journey; 1 Listing; operator lists it; 2 KYC; identity checks; 3 Claim; eligibility on chain; 4 Funding; quote token deposit; 5 Order; signed in the Portal; 6 Match; price, then time; 7 Settlement; both legs or neither; 8 Records; positions and reports.

Steps 1 to 4 prepare the instrument and the investor, steps 5 to 7 run on every order, and step 8 reads what the first seven wrote.

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

- The token that the venue lists already exists.
- A platform administrator or the organisation owner lists the instrument, signing with a wallet that holds the venue operator role on the venue.
- The organisation's operations signer holds the venue submitter role.
- The investor has a custodial wallet, whose keys the platform's custody provider holds and signs with after the investor verifies the wallet, or a self-custody wallet, whose keys the investor holds. The platform holds no key for a self-custody wallet, so the investor's wallet signs each order itself, as [Orders from a self-custody wallet](#orders-from-a-self-custody-wallet) describes.

Every order commits its units in the venue's escrow, for a DALP token and a plain ERC-20 alike: the venue deposits whatever the trader's free escrow balance lacks from the trader's wallet and locks the order's amount, so the units cannot be spent twice. Every trade has two legs, the base token and the quote token, and both settle through that escrow.

## Step 1: an operator lists the instrument [#step-1-an-operator-lists-the-instrument]

An operator lists the instrument in the Console under "Venues", with "List instrument" in the header of the venue page. The wizard sets the base and quote token, the tick size (the smallest price step) and lot size (the smallest quantity step), the maker and taker fees in basis points, the market-order protection band (a limit on how far a market order may walk the book), and the trading calendar. The platform checks the listing before it accepts it, and the instrument stays pending until its listing ceremony completes. That checklist covers the feed writer, the fee account, a trading schedule or collection window, the trading model, the prices, and the venue's listing rules. [Venue operations](https://docs.settlemint.com/docs/console/asset-lifecycle/venues) describes every field and the ceremony checklist, and [Venue market settings](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/instrument#most-listing-choices-get-a-later-edit-some-do-not) says which choices can be edited later.

![List a new instrument wizard at the Pair step](https://docs.settlemint.com/docs/screenshots/console-venue-journey-list-market.light.en.webp)

[Screenshot] The "List a new instrument" wizard at its "Pair" step, with the base and quote token fields.

The venue's "Listing rules" page sets a default price band, initially Off: a static minimum and maximum quote price, or a dynamic percentage range. Each instrument can inherit it, turn it off, or override it. A dynamic band starts around the previous official close, expands only the side reached by a trade up to its cap, and resets at the next session close. [Venue operations](https://docs.settlemint.com/docs/console/asset-lifecycle/venues) covers these controls and their effect on resting orders.

The same page can hold starting values for the fees, the fee account, the protection band and the holding period. The wizard opens with them filled in, and the operator can change each one. The values are copied when the wizard opens, so the listed instrument keeps its own after that. The page can also limit the order types and the time in force that every instrument on the venue accepts. The limit reaches instruments already listed, and a listing that asks for an option outside it is refused.

Listing does not require a primary offering. No listing check asks about one, so a token that was issued directly and never sold through an offering can be listed.

The Platform API keeps the earlier name for an instrument: its routes use `/markets` and the instrument's id is `marketId`.

| What happens | Route |
| --- | --- |
| The wizard checks the venue roles, the operations signer, and that the pair is free | `GET /api/v2/addons/trading-venues/:venueAddress/listing-preflight` |
| The operator creates the instrument | `POST /api/v2/addons/trading-venues/:venueAddress/markets` |
| The operator halts, resumes, or delists it | `POST /api/v2/addons/trading-venues/:venueAddress/markets/:marketId/transitions` |

## Step 2: the investor passes identity checks [#step-2-the-investor-passes-identity-checks]

The investor completes know your customer (KYC) identity verification on the "Profile" page of the Investor portal, which opens from the account menu. Onboarding sets up the investor's wallet and does not include identity verification. On the "Information" card, the investor enters personal details, such as name, country of residence, national ID, date of birth and residency status, and selects "Save". Under "Identity documents", the investor selects "Create new draft" when no draft is open, uploads the documents, and selects "Submit for review". The saved details show "Waiting for review" until an operator reviews them in the Console, and then show "Approved" or "Changes requested". An approval updates the status of the details and does not issue the eligibility claim. The claim comes from the provider's verdict, as [Step 3](#step-3-the-eligibility-claim-reaches-the-chain) describes, or from a trusted issuer in the Console, as [Verify a participant](https://docs.settlemint.com/docs/console/participants/verify-a-participant) describes.

When the organisation has a verification provider and the investor's identity has no eligibility claim for KYC, the page also shows the provider's check. For that check the platform asks the provider for a short-lived SDK token, and the investor sends documents to the provider directly. After the investor finishes, the page checks for the claim every 10 seconds for up to 15 minutes and shows "Identity verified" once it arrives. The sequence an operator or an integrator runs, from creating the user to registering the identity, is in [Onboard an investor](https://docs.settlemint.com/docs/api-reference/guides/onboard-an-investor). Adding the provider is a one-time Console task in [Compliance providers](https://docs.settlemint.com/docs/console/compliance/compliance-providers).

![The Investor portal Profile page with the Information card, Identity details and Identity documents](https://docs.settlemint.com/docs/screenshots/portal-venue-journey-identity-checks.light.en.webp)

[Screenshot] The "Information" card of the Profile page, with the "Approved" state, the identity fields and the "Identity documents" section.

The card shows the first name, last name, country of residence and national ID fields, then "Identity details" with date of birth and residency status, each field with its own status, and the "Save" button. The national ID is masked in this image.

| What happens | Route |
| --- | --- |
| An identity manager creates the user and the custodial wallet | `POST /api/v2/users` |
| The identity manager registers the identity under a country | `POST /api/v2/system/identity-registrations` |
| The investor's app requests the provider SDK token | `POST /api/v2/compliance/subjects/sdk-access-token` |
| "Save" stores the personal details | `PATCH /api/v2/users/:userId/profile` |
| "Create new draft" opens a document draft | `POST /api/v2/kyc-profiles/:userId/versions` |
| "Submit for review" submits the draft | `POST /api/v2/kyc-profile-versions/:versionId/submissions` |

## Step 3: the eligibility claim reaches the chain [#step-3-the-eligibility-claim-reaches-the-chain]

The eligibility claim is the on-chain statement that an identity passed a check, such as KYC. An approved provider verdict issues the claim, a rejected verdict revokes it, and a monitoring alert at or above the topic's threshold can revoke it later. The investor does nothing in this step. The platform acts on the provider's signed verdict, or a trusted issuer issues the claim in the Console.

The claim matters twice. The venue's admission policy can require named claim topics, such as a KYC topic, before a wallet sees or trades an instrument, and each token's own rules judge every delivery. A missing, expired, or revoked claim rejects a new order with `identity-not-verified`. A wallet on the security's block list or frozen on the base token is rejected with `suspended-wallet`. Orders that already rest on the book stay there, because revoking a claim does not cancel them. A fill delivers only when each recipient still passes the receiving token's checks, so a buyer who lost the claim fails at delivery while a seller who lost it still delivers units already committed to the escrow. Cancel the participant's resting orders when a claim is revoked. An unregistered wallet is rejected with `unregistered-wallet`, a wallet outside the venue's admission policy with `wallet-not-admitted`, and an order whose recipient may not receive one of the instrument's tokens with `ineligible-wallet`. A sell of units that the base token's Time lock still holds is rejected with `units-time-locked`. The response gives the seconds until the next units unlock.

An operator reads the registration state with `GET /api/v2/system/identity-registration-statuses`.

## Step 4: the investor funds the wallet [#step-4-the-investor-funds-the-wallet]

An order needs the quote token for a buy and the base token for a sell. The investor opens "Wealth", then "Portfolio" in the Investor portal and selects "Deposit". The button appears only on an instance that has custody operations or the bank rail enabled, and the dialog offers "From a wallet" only with custody operations. A bank rail adds "By bank transfer". "From a wallet" shows the investor's [custody gateway](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-gateway) address as a QR code, as text, and with a copy button, and lists the accepted coins. Send only an accepted coin to that address, because anything else cannot be credited automatically. The gateway mints [custody receipts](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-receipt) for the coins it receives. While the gateway is paused, the dialog reads "This gateway is paused. Do not send a deposit until it resumes." An investor whose organisation has not created a gateway yet sees "No gateway yet".

![Deposit dialog with the gateway address, its QR code and the accepted coins](https://docs.settlemint.com/docs/screenshots/portal-venue-journey-fund-wallet.light.en.webp)

[Screenshot] The Deposit dialog shows "Your gateway address" as a QR code and as text with a copy control, an "Accepted coins" line, and a "Receipt balances" card underneath.

| What happens | Route |
| --- | --- |
| The dialog reads the investor's gateway | `GET /api/v2/addons/custody-gateways/gateways/mine` |
| The dialog lists the accepted coins | `GET /api/v2/addons/custody-gateways/gateways/:gatewayAddress/tokens` |

Before the first order the ticket may ask for a trading authorisation. The investor approves the venue's escrow, as an ERC-20 approval, for the amount the ticket shows, for a DALP token and a plain ERC-20 alike. An order that free escrow balance already covers needs no approval. [Trading](https://docs.settlemint.com/docs/console/my-assets/trading#before-you-start) lists the exact amounts.

## Step 5: the investor places an order [#step-5-the-investor-places-an-order]

The investor opens "Wealth", then "Trading" in the Investor portal, selects the instrument, and fills the order ticket. When the instrument has a price band, the ticket shows its bounds on the "Price band" line. A price outside the band disables "Place buy order" or "Place sell order", and the ticket names the band beside the button, so the order never reaches the venue. The ticket also disables Place and names the pause beside the button while the venue is paused, and it follows a pause or resume without a reload. Both price bounds are inclusive. Selecting "Place buy order" or "Place sell order" opens a review card that shows the amount "Reserved for this order". "Confirm buy order" or "Confirm sell order" asks the investor to verify the wallet, and the platform signs the order through the investor's custodial wallet. The ticket answers "Your order is accepted." once the venue has taken the order.

![The Investor portal trading screen for EUROC / AEDT with the order book and the Buy order ticket](https://docs.settlemint.com/docs/screenshots/portal-venue-journey-place-order.light.en.webp)

[Screenshot] The EUROC / AEDT header with "Session open · Live" and the session figures, the chart, the order book and recent trades, and the order ticket on "Buy" with the limit price, quantity, "Reserved for this order" and "Place buy order", above the balances.

Above the order book, "Price step" groups the resting levels into price buckets. Its first option is the instrument's own price step, one tick, which shows every resting price. The next options are 2, 5, 10, 50 and 100 ticks, each named by the price it adds up to. A bucket sits on a multiple of its step, so bids round down and asks round up, and its size is the sum of the levels inside it. Selecting a bucket fills the ticket's price. The Console trading screen groups its order book the same way.

The ticket and the review card show the exact amount "Reserved for this order". In the review card, prices, order value, fees, VAT and totals in the quote token share one decimal precision, long enough to retain every amount, with the price step as the minimum. Trailing zeros align the figures without changing what is reserved or charged. Base quantities keep the lot size's precision. Both the Console and Investor portal follow this rule.

Once the venue has taken the order, the ticket empties the quantity and puts "New order" where "Place buy order" or "Place sell order" was. Selecting "New order", or changing any field, clears the accepted note and starts the next order.

The venue accepts the signed order first. It then deposits any shortfall from the investor's wallet into its escrow and locks the order's amount, so the free balance drops and the locked balance rises. The order shows "Reserving balance" until the commitment confirms on chain, and it joins the book after that.

| What happens | Route |
| --- | --- |
| The platform signs the order with the investor's custodial wallet, and the venue takes it | `POST /api/v2/addons/trading-venues/:venueAddress/orders` |
| The caller polls a placement the API accepted asynchronously | `GET /api/v2/addons/trading-venues/:venueAddress/order-placements/:orderId` |
| The investor cancels an open order | `DELETE /api/v2/addons/trading-venues/:venueAddress/orders/:orderId` |

The venue checks the order before it reaches the book and rejects it with a named reason. The reasons include `venue-paused` (a venue admin must resume the whole venue), `market-halted`, `market-suspended` and `market-not-live` (the instrument is not trading), `authorization-insufficient` (the allowance is too low), `above-price-band` and `below-price-band` (the limit price is outside the range), and `desk-limit-exceeded` (the order is over the trading limit an operator set for the wallet), and `invalid-order` (a stop whose trigger price is already on the wrong side of the last trade). An instrument past its trading cut-off accepts no new order and the venue rejects it with `maturity-cutoff-reached`. The venue cancels the instrument's resting orders and releases their holds. For a bond, the cut-off is an instrument setting, the number of days before the bond's maturity date at which trading stops. The default of 0 days stops trading at maturity. For a rights token, the cut-off is the trading end of its rights issue. A dynamic band without a previous-close anchor blocks trading with `no-band-anchor`. [Trading](https://docs.settlemint.com/docs/console/my-assets/trading#troubleshooting) explains the fix for each.

### Orders from a self-custody wallet [#orders-from-a-self-custody-wallet]

A wallet whose keys the investor holds (a Privy embedded wallet, MetaMask, or a smart wallet one of them controls) follows the same steps, with one difference: the platform has no key to sign the order, so the investor's wallet signs it. In the Investor portal the review card reads "Sign in wallet". The investor signs, then selects "Place buy order" or "Place sell order" to submit the signed order. Investors whose keys the platform holds see no change.

An integration that builds its own front end on the SDK does this in three calls:

1. Request the order signature (`POST /api/v2/addons/trading-venues/:venueAddress/order-signatures`) with the order fields and no wallet signature. For a self-custody maker the venue answers `409` with `dapi.runtime.EXTERNAL_MESSAGE_AUTHORIZATION_REQUIRED`. The response carries the custody account and `signingPayload.typedData`, the order as EIP-712 typed data with `EIP712Domain` declared, ready for `eth_signTypedData_v4`.
2. Have the investor's wallet sign that exact payload. Do not change any field, because the venue checks the signature against the same order.
3. Send the first request again with the signature in `externalMessageAuthorization.signature`. The venue checks that the signature is a standard 65-byte signature from the account's signing key and that the smart wallet accepts it, then returns the signed order. Place it with `POST /api/v2/addons/trading-venues/:venueAddress/orders` as for any signed order.

A wrong signature, or a wallet signature sent for a maker whose keys the platform holds, fails with `400` and `dapi.runtime.EXTERNAL_MESSAGE_AUTHORIZATION_INVALID`. Send the request again without a signature to read the payload, then sign it.

## Step 6: the venue matches orders [#step-6-the-venue-matches-orders]

The venue keeps one order book per instrument and matches by price, then by arrival time. An instrument runs in one of two modes. A continuous instrument matches an incoming order against the resting book at once. An auction-only instrument collects orders during a window and clears them together at a single price, the price that matches the most volume. What the auction leaves unfilled follows the instrument's remainder rule. An instrument set to "Carry to the book" keeps good-till orders resting, with their holds, for the next auction. An instrument set to "Cancel remainders" cancels them. The listing wizard starts with "Carry to the book", and the choice is fixed once the instrument is listed. The status badge in the trading screen header says which phase the instrument is in, for example "Pre-open", "Opening auction", "Closing auction", "Session open · Live", "Trade at last", or "Session closed". A public continuous instrument can end its day with a "Closing auction", which collects orders and crosses them at one price, and then in "Trade at last", where orders trade only at the last price until the close.

Continuous fills and auction clearing prices stay inside the effective price band. A market order keeps its separate signed protection limit, and its fills must satisfy both limits. Saving a tighter policy cancels excluded resting orders and restores their reserved balances.

Every participant who can see the instrument sees its trades, candles and ticker, and the book to the depth their access allows. During pre-open and collection, the instrument's indicative price and quantity follow its publication setting. The screens do not show who is on either side. The venue contract's trade events name the buyer's and the seller's wallets on chain, so anyone who reads the chain can link a trade to both wallets.

| What the screen shows | Route |
| --- | --- |
| The order book | `GET /api/v2/addons/trading-venues/:venueAddress/markets/:marketId/book` |
| The trades tape | `GET /api/v2/addons/trading-venues/:venueAddress/markets/:marketId/trades` |
| Candles and the 24-hour ticker | `GET .../markets/:marketId/candles` and `GET .../markets/:marketId/ticker` |
| Live updates | `GET .../markets/:marketId/stream` |

## Step 7: the fill settles [#step-7-the-fill-settles]

A match is not a delivery by itself. The venue stages each fill and submits fills to the chain in batches. Within a batch, every fill moves both legs together. On an instrument with no holding period, the base units go to the buyer's recipient and the quote units, less the fee, to the seller's recipient in the filling transaction. With a holding period, the fill relocks both legs in the escrow until delivery. A fill that cannot complete leaves both legs where they were. The platform tries a passing failure again, and a fill that still cannot settle waits as a held fill until an operator retries or busts it, as [Held fills](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/held-fills) describes. It does not stop the other fills in the batch. No party pays without receiving.

Each leg still passes its token's own transfer rules, so a match can fail at this point if a holder lost eligibility after the order was placed. An instrument can also set a holding period. During it the trade is recorded and priced, and its delivery is pending. An operator can undo a pending delivery through a trade bust, with a second operator's approval while the organisation requires one, as [Trade busts](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/trade-busts) describes. An instrument with no holding period delivers inside the filling transaction.

The "Your trades" tab on the trading screen lists each fill with its price, quantity, fee, and status: "Pending delivery", "Delivered", or "Undone". Charged fees share the longest exact decimal precision among the listed fees, with the price step as the minimum, so even a fee of one smallest token unit stays visible. A fill shows its fee as "Not charged yet" until its settlement transaction lands, and shows the charged fee from then on, even while it awaits delivery. "Order history" shows each order's final state and, for an order that closed unfilled, the reason.

When a pending delivery is undone, both legs unlock into their owners' free escrow balances, and each owner withdraws them to the wallet from the Balances panel. The platform does not offer the undone lot again and does not return it to the book, and the orders' filled figures leave it out. The owner of a limit order with an undone lot can choose Place again on that order. It opens the new-order ticket with the same side, limit price and the undone quantity, and the original expiry if it is still in the future. You review and sign it as a new order, which gets new time priority. The side that failed has no Place again. The order on the side that failed shows "Settlement failed" with the undo reason. Every other order on the trade keeps its own status and close reason and adds a note that a trade on it was undone. An open order stays open for the rest of its quantity. The same rules apply in the Investor portal.

| What the screen shows | Route |
| --- | --- |
| Fills and their delivery status | `GET /api/v2/addons/trading-venues/:venueAddress/blotter` |
| The investor's orders | `GET /api/v2/addons/trading-venues/:venueAddress/orders` |
| The investor's reservations | `GET /api/v2/addons/trading-venues/:venueAddress/reservations` |
| The investor's escrow balances | `GET /api/v2/addons/trading-venues/:venueAddress/balances` |

The fills, orders and refused orders reads answer one page at a time, newest first: 50 rows when the request sends no `limit`, and at most 200. Send each page's `meta.nextCursor` back as `cursor` to read the next one, until it is `null`. Only the first page carries `meta.total`. The blotter takes a `status` filter, so a client that wants only the fills awaiting delivery asks for `status=pending-delivery` instead of reading every fill.

The orders read answers the caller's own orders, whatever `status` it filters by, even when the caller also operates the venue. A venue operator reads every participant's orders through `GET /api/v2/addons/trading-venues/:venueAddress/orders/operator`, or by sending an operator filter such as `participant` or `side`.

A reservation reads `committing: true` while its order's escrow commitment is still on its way: the venue holds the commitment, but the escrow balances and the token allowance do not show its pull yet. Add those amounts to a new order's before you compare it with the free escrow balance and the allowance to the venue's escrow. The Console and the Investor portal tickets do this before they offer "Authorize" or place an order.

A reservation reads `refundExhausted: true` once the venue spent every retry on refunding it. The escrow still holds those units, and they come back only after an operator reconciles the refund. An `active` reservation of an order that no longer works, with `refundExhausted: false`, is a refund the venue is still sending: an immediate-or-cancel order that fills in part keeps its remainder locked until that refund lands, a few seconds after the fill settles. The Console and the Investor portal desks show "Reserved for orders" as loading during that time, on the leg of the refund's token in the market the order was placed in, and show the units as reserved again only when the refund is spent. A refund in another market or another token does not hold this market's figures back.

## Step 8: positions, statements, and shareholder lists [#step-8-positions-statements-and-shareholder-lists]

The investor reads positions in the Investor portal under "Wealth", then "Portfolio". The "Holdings" tab lists balances read from indexed chain state, so a position updates once the block that settled the trade is indexed. Its "Value" column shows each holding in the organisation's base currency. The "Returns" tab shows the income those holdings earn: dividends, coupons, and interest. It also lists "Realized disposals": each burn or transfer out of the investor's wallets, with its realised profit or loss.

![The Holdings tab of the Investor portal Portfolio with each holding's balance and value](https://docs.settlemint.com/docs/screenshots/portal-venue-journey-positions.light.en.webp)

[Screenshot] The "Holdings" tab with the portfolio value chart, and below it a table with one row per token showing "Symbol", "Balance", "Value", "Unrealized P&L" and a "Transfer" action.

| What it shows | Route |
| --- | --- |
| Holdings and their base-currency value | `GET /api/v2/user-asset-balances` |
| Income returns | `GET /api/v2/portfolio/returns` |
| Realised disposals | `GET /api/v2/user-realized-pnl` |
| The caller's statements | `GET /api/v2/reporting/statements`, then `GET /api/v2/reporting/statements/:statementId/download` |
| One security's holders at a record block | `GET /api/v2/reporting/shareholder-lists/:tokenAddress`, then `GET .../download` |
| Scheduled and delivered lists | `GET /api/v2/reporting/shareholder-lists/:tokenAddress/deliveries` and `POST /api/v2/reporting/shareholder-lists/:tokenAddress/deliveries` |

The "Statements" tab on "Portfolio" shows one row for each wallet and period, with the columns "Period", "Wallet", "Status", and "Download". A statement lists the opening and closing balances and the movements of one wallet over a period. The organisation's statement policy sets how often the platform produces statements, and each one appears once its period has closed. Before the first period closes, the tab reads "No statements yet". "Status" reads "Incomplete" when, for any security, the opening balance plus the movements does not equal the closing balance, and "Reconciled" otherwise. Do not use an incomplete statement as a record of the wallet's balances. Each row offers "Download CSV", "Download Excel workbook", or "Download PDF" for each format the platform produced. See [Investor statements](https://docs.settlemint.com/docs/api-reference/guides/investor-statements).

A shareholder list is the register of holders of one security at one record block, a chosen chain block that fixes the balances, which an issuer uses after an auction cycle or at month end. On the "Holders" tab of the security in the Console, the "Export" menu offers "Holder register…", "Registrar file…", "Beneficial owners…", and "Issuer deliveries…" only for a security created with the Historical balances feature. Only organisation owners, platform administrators, and accounts with the system admin, auditor, compliance manager, or system manager role see them. Every other account sees only "This table as CSV". "Holder register…" opens the "Export holder register" sheet, which has a "Register" tab, a "Registrar file" tab, a "Beneficial owners" tab, and a "Deliveries" tab. The list is also available through the API. See [Issuer shareholder list](https://docs.settlemint.com/docs/api-reference/guides/issuer-shareholder-list).

The "Register" tab has "Deliver to issuer", which schedules a delivery. Only organisation owners and platform administrators see it. It is unavailable when the units held do not add up to total supply, or when no list exists at that record block. The "Deliveries" tab lists each delivery with its trigger: "After auction", "Requested", "Month end", or "Correction". "Requested" is a list an operator asked for with "Deliver to issuer". The API calls that trigger `scheduled`. A "Correction" supersedes an earlier delivery and states why. For a security that trades by auction, the platform also produces the list itself and stores it for the issuing organisation.

The platform emails the issuer's owners a notice when it delivers a list, or when it cannot produce one and marks the delivery "Refused". A delivery for a security created without the Historical balances feature is marked "Refused". The platform sends the email only when it has email delivery configured.

## The session close [#the-session-close]

An instrument follows its trading calendar. At the close the session ends, the venue accepts no new orders except "Day" limit orders for the next session, and the instrument computes its official close price from the session's settled trades. The instrument's close methodology sets the price: the last trade, or a volume-weighted average price over a configured window. A session with no eligible trade follows the instrument's "No-trade fallback": by default the auction price, then the previous close, or the previous close directly. Only a token's reference instrument publishes its official close to the token's price feed. An operator changes the methodology under "Edit official close" on the instrument detail.

A closed session leaves resting orders in place, except "Day" orders, which the venue expires at the close. An order placed as "Good till cancelled" rests through the close and is on the book at the next open. For a continuously traded security, the platform schedules a "Month end" delivery once the last trading day of the month has closed. To deliver a list for another record block, use "Deliver to issuer" as [Step 8](#step-8-positions-statements-and-shareholder-lists) describes.

## Many instruments, one quote token each [#many-instruments-one-quote-token-each]

Each instrument has exactly one quote token. A venue lists many instruments, and different instruments on the same venue can use different quote tokens. For example, one venue can list EUROC priced in AEDT and SGDT priced in EUROC.

Three rules follow from this design:

- A trade settles in the instrument's quote token. Both legs move on chain in the base token and that quote token. The platform does not convert currencies at order time, so a buyer needs a balance of the quote token and a seller receives it.
- The fee is charged in the quote token, at the instrument's maker and taker rate.
- Valuation is a separate step. The platform converts each holding into the organisation's base currency through the exchange rates the organisation tracks, and the "Value" column on the "Holdings" tab shows the result. [Exchange rates](https://docs.settlemint.com/docs/console/organisation-settings/exchange-rates) shows which currencies are tracked and the latest rate for each.

When no rate path exists, or a token has no price, the "Value" column shows a dash. It does not estimate a value. A position in a stablecoin quoted in a currency the organisation does not track therefore trades normally and appears in the holdings, but it has no value in the base currency until the organisation adds a rate for it.

## How fast the screens update [#how-fast-the-screens-update]

Market data arrives live over the instrument stream. The platform has no push channel to an individual user, so the other screens read fresh data when the browser window regains focus and at these moments:

| Screen | When it refreshes |
| --- | --- |
| Order book, trades, ticker, and candles | Live: the instrument stream carries the book and the trades, and each trade print refreshes the ticker and candles |
| Open orders and your trades | On each trade print, after the investor places or cancels an order, and after the platform indexes a block that changes the venue, checked every 15 seconds |
| Reservations | After the investor places or cancels an order, when an order or fill on the trading screen changes state, and after the platform indexes a block that changes the venue, checked every 15 seconds |
| Holdings | After the investor places or cancels an order, and when an order or fill on the trading screen changes state |
| Portfolio figures | After the investor places or cancels an order |

A position changes after the platform indexes the block that settled the trade, so it can lag the fill. "Your trades" is the first place a fill shows. The platform does not push positions to the user.

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

- After a full pass, "Your trades" lists the fill as "Delivered" with the fee in the quote token, or as "Pending delivery" while a holding period runs, with the charged fee once the settlement transaction has landed and "Not charged yet" before that.
- "Order history" shows the order as "Filled".
- For a buy, "Holdings" shows the higher base balance and the lower quote balance once the settlement block is indexed. A sell shows the reverse.
- The operator sees the same fill in the "Instrument activity" tile of the instrument detail under "Venues".

## Frequently asked questions [#frequently-asked-questions]

### Can an investor trade a token that was never sold in a primary offering?

Yes. No check requires an earlier offering, and listing needs no token feature. The instrument stays pending until its listing ceremony completes, as [Step 1](#step-1-an-operator-lists-the-instrument) describes.

### Does a trade in one quote token change a balance in another currency?

No. A trade moves only the instrument's base token and its quote token. The organisation's base currency matters only when the Portfolio values the holdings.

### Why does a position lag a fill?

Positions come from indexed chain state. The fill shows in "Your trades" first, and the holding changes after the platform indexes the settlement block.