Trading venue flows
Read venue markets, calendars, and market data, place signed orders and quoting batches, manage watchlists, stream live depth, and administer markets, bands, participants, busts, and desk limits through the DALP v2 API.
Trading venue flows
The Trading Venue exposes a v2 route group for orderbook trading: market, calendar, and market-data reads, a live stream, signed-order placement and cancellation, quoting batches, participant-scoped reads, and personal watchlists. Venue-operator administration covers markets, bands, private-market participants, trade busts, and desk limits. Every operation requires a session or API key with an active organization. Chain-writing mutations answer 202 with a status URL; poll it as described in Transaction tracking.
Use this page to map the route surface and its semantics. Use the API Reference for exact request and response fields, and the generated SDK operations named below from @settlemint/dalp-sdk/operations.
Route surface
Market, calendar, and market-data reads
Reads are scoped to the active organization and safe to repeat. A private market answers every read as not-found for callers without an approved wallet, exactly as if the market did not exist.
| Route | SDK operation | Returns |
|---|---|---|
GET /api/v2/addons/trading-venues | v2AddonsTradingVenueVenuesList | The Trading Venue contracts serving the organization's network. |
GET /api/v2/addons/trading-venue-markets | v2AddonsTradingVenueMarketsList | Every visible market, including halted and pending listings. |
GET /api/v2/addons/trading-venue-markets/{marketId} | v2AddonsTradingVenueMarketsRead | One market with its trading grid, fee schedule, protection band, trading mode, visibility, session state, and close methodology. |
GET /api/v2/addons/trading-venue-markets/{marketId}/book | v2AddonsTradingVenueBook | A sequence-numbered depth snapshot with the indicative auction price during preopen and auction collection. |
GET /api/v2/addons/trading-venue-markets/{marketId}/trades | v2AddonsTradingVenueTrades | Most recent trades, newest first, capped by limit (1 to 500, default 100), each with its settled or busted status. |
GET /api/v2/addons/trading-venue-markets/{marketId}/candles | v2AddonsTradingVenueCandles | OHLC candles with volume for one interval: 1m, 5m, 15m, 1h, 4h, or 1d. Busted trades are excluded. |
GET /api/v2/addons/trading-venue-markets/{marketId}/ticker | v2AddonsTradingVenueTicker | Trailing 24-hour statistics: last price, open, high, low, volume, trade count. Busted trades are excluded. |
GET /api/v2/addons/trading-venue-markets/{marketId}/calendar | v2AddonsTradingVenueCalendarRead | The market's trading calendar: timezone, weekly template, exceptions, the published uncross window width, and materialized session occurrences with official closes. |
GET /api/v2/addons/trading-venue-market-calendars | v2AddonsTradingVenueCalendarsList | A paginated list of every visible market's calendar summary: timezone, mode, session state, status. |
GET /api/v2/addons/trading-venue-markets/{marketId}/stream | v2AddonsTradingVenueStream | Server-sent events: depth snapshots, diffs, trade batches, indicative auction quotes, heartbeats. |
Amounts and prices travel as integer strings in token base units and price ticks. Market status is pending, live, halted, or delisted; sessionState is the orthogonal session axis: closed, preopen, open-continuous, or auction-collection. Calendar occurrences publish scheduled boundaries only: the randomized uncross instant inside the published window is never returned by any route or stream.
The stream's first event is a full sequence-numbered snapshot; later events carry diffs keyed by their sequence span. Snapshots and diffs key on the engine log sequence, not the trade sequence, so preopen book changes reach subscribers without a trade. A sequence gap means the client must reconnect for a fresh snapshot instead of rendering stale depth. The stream is consumed same-origin by the Console; a cross-origin request answers 404. Server-to-server integrations poll the book snapshot and order results by sequence.
Participant reads
These reads are additionally scoped to the selected participant.
| Route | SDK operation | Returns |
|---|---|---|
GET /api/v2/addons/trading-venue-orders | v2AddonsTradingVenueOrdersList | Orders placed by wallets the participant controls, filterable by marketId and status. |
GET /api/v2/addons/trading-venue-blotter | v2AddonsTradingVenueBlotter | The trade blotter: fills newest first, with the participant's side, fee, and settled or busted status per fill. |
GET /api/v2/addons/trading-venue-reservations | v2AddonsTradingVenueReservationsList | Reserved balances backing the participant's open orders. |
Order status is pending_reservation, armed, working, partially_filled, filled, cancelled, expired, rejected, or pruned. armed is a dormant stop order holding no reservation. Closed orders carry a closeReason naming why the engine closed them, band and threshold rejections included.
Order mutations
| Route | SDK operation | Effect |
|---|---|---|
POST /api/v2/addons/trading-venue-orders | v2AddonsTradingVenueOrdersPlace | Accepts an EIP-712-signed order after eligibility, desk-limit, trading-authorization, fee-cap, band, and threshold checks, then queues the reserved-balance transaction. With triggerTick, arms the order as a dormant stop instead: nothing is reserved until the trigger print confirms. |
POST /api/v2/addons/trading-venue-order-batches | v2AddonsTradingVenueOrdersBatch | Applies a quoting batch of place, replace, and cancel operations on one market with per-order failure isolation. Reservation changes settle as net deltas: a flat batch emits zero chain transactions. Answers synchronously with per-operation results. |
DELETE /api/v2/addons/trading-venue-orders/{orderId} | v2AddonsTradingVenueOrdersCancel | Queues the on-chain cancellation so the signed order can never fill, and marks it cancelled on the book. Cancels dormant stops too. |
An order becomes matchable only after its reservation confirms. Poll the 202 status URL before you treat an order as placed or cancelled on chain. The signing payload, typed-data domain, and field semantics are documented in Place and cancel orders; batch semantics in Quote in bulk; the stop contract in Place stop orders.
Watchlists
Watchlists are personal, scoped to the authenticated user, and never operator-gated. Entry reads respect private-market visibility: an invisible market is silently absent.
| Route | SDK operation | Effect |
|---|---|---|
GET /api/v2/addons/trading-venue-watchlists | v2AddonsTradingVenueWatchlistsList | Lists your watchlists, paginated. |
POST /api/v2/addons/trading-venue-watchlists | v2AddonsTradingVenueWatchlistsCreate | Creates a named watchlist. |
GET /api/v2/addons/trading-venue-watchlists/{watchlistId} | v2AddonsTradingVenueWatchlistsRead | One watchlist with its currently visible entries. |
PUT /api/v2/addons/trading-venue-watchlists/{watchlistId} | v2AddonsTradingVenueWatchlistsRename | Renames the watchlist. |
DELETE /api/v2/addons/trading-venue-watchlists/{watchlistId} | v2AddonsTradingVenueWatchlistsDelete | Deletes the watchlist and its entries. |
POST /api/v2/addons/trading-venue-watchlists/{watchlistId}/entries | v2AddonsTradingVenueWatchlistEntriesAdd | Adds a visible market to the watchlist; re-adding is a no-op. |
DELETE /api/v2/addons/trading-venue-watchlists/{watchlistId}/entries/{marketId} | v2AddonsTradingVenueWatchlistEntriesRemove | Removes a watched market; removing an unwatched one is a no-op. |
Another user's watchlist id answers not-found on every one of these routes.
Market administration
These routes require the venue-operator platform role: platform administrators and organization owners. The venue contract enforces its own on-chain operator role check as well.
| Route | SDK operation | Effect |
|---|---|---|
POST /api/v2/addons/trading-venues | v2AddonsTradingVenueVenuesCreate | Queues venue-contract creation from the system's registered Trading Venue factory. |
POST /api/v2/addons/trading-venue-markets | v2AddonsTradingVenueMarketsCreate | Queues on-chain market creation, trading mode, visibility, and auction-remainder configuration included, and records the listing as pending until the listing ceremony completes. |
PUT /api/v2/addons/trading-venue-markets/{marketId} | v2AddonsTradingVenueMarketsUpdate | Updates off-chain market settings such as the close methodology. Rejects any change to the trading mode or visibility: both are immutable after listing. |
POST /api/v2/addons/trading-venue-market-halts | v2AddonsTradingVenueMarketsHalt | Stops matching and new order acceptance immediately and queues the on-chain halt. Resting orders stay; submitted batches complete. |
DELETE /api/v2/addons/trading-venue-market-halts | v2AddonsTradingVenueMarketsResume | Reopens matching and order acceptance and queues the on-chain resume. |
POST /api/v2/addons/trading-venue-market-delistings | v2AddonsTradingVenueMarketsDelist | Permanently closes the market: resting orders and dormant stops cancelled, reserved balances released. Cannot be reversed. |
PUT /api/v2/addons/trading-venue-market-fee-schedules | v2AddonsTradingVenueMarketsSetFees | Sets the maker and taker fees in basis points of the quote leg. Resting orders whose signed fee cap falls below the new schedule are pruned. |
Bands and thresholds
Band and threshold writes are off-chain configuration: no queue, no chain transaction, effective at intake immediately.
| Route | SDK operation | Effect |
|---|---|---|
GET /api/v2/addons/trading-venue-markets/{marketId}/bands | v2AddonsTradingVenueBandsRead | The market's static band, its session anchor, the dynamic band, and the maximum quantity and notional thresholds. |
PUT /api/v2/addons/trading-venue-markets/{marketId}/bands | v2AddonsTradingVenueBandsPut | Full-replacement write of bands and thresholds; null deactivates a control. Resting orders are untouched. |
GET /api/v2/addons/trading-venue-markets/{marketId}/band-preview | v2AddonsTradingVenueBandsPreview | Counts the resting orders that would fall outside candidate band and threshold values. |
POST /api/v2/addons/trading-venue-market-band-prunes | v2AddonsTradingVenueBandsPrune | Explicitly mass-cancels the resting orders outside the current settings and releases their reservations, reporting the pruned order ids. |
Private-market participants
| Route | SDK operation | Effect |
|---|---|---|
GET /api/v2/addons/trading-venue-markets/{marketId}/participants | v2AddonsTradingVenueParticipantsList | The market's approved participant wallets, paginated. |
POST /api/v2/addons/trading-venue-markets/{marketId}/participants | v2AddonsTradingVenueParticipantsAdd | Approves a wallet; the market becomes visible to the participant controlling it. |
DELETE /api/v2/addons/trading-venue-markets/{marketId}/participants/{walletAddress} | v2AddonsTradingVenueParticipantsRemove | Revokes a wallet, prunes its resting orders and dormant stops, releases its reservations, and reports the pruned order ids. |
Calendars
| Route | SDK operation | Effect |
|---|---|---|
PUT /api/v2/addons/trading-venue-markets/{marketId}/calendar | v2AddonsTradingVenueCalendarPut | Full-replacement write of the market's trading calendar: timezone, weekly template, and dated exceptions. Overrides are calendar edits effective from now. |
Trade busts
Busting follows maker-checker: a proposal, then a decision by a distinct operator. The pre-check runs at proposal and again at approval; a refusal creates or executes nothing.
| Route | SDK operation | Effect |
|---|---|---|
GET /api/v2/addons/trading-venue-trade-busts | v2AddonsTradingVenueTradeBustsList | Bust proposals and their states, paginated: proposed, approved, rejected, executed, or failed. |
POST /api/v2/addons/trading-venue-trade-busts | v2AddonsTradingVenueTradeBustsPropose | Runs the pre-check (settlement confirmation, order closure, bust window, counterparty balances, compliance path) and records the proposal. A failing pre-check refuses with the reason and records nothing. |
POST /api/v2/addons/trading-venue-trade-bust-approvals | v2AddonsTradingVenueTradeBustsApprove | Approves as a distinct operator, re-runs the full pre-check, and executes the compensating reversal with the fee refund atomically. |
POST /api/v2/addons/trading-venue-trade-bust-rejections | v2AddonsTradingVenueTradeBustsReject | Rejects the proposal as a distinct operator; the decision is audited. |
Desk limits
| Route | SDK operation | Effect |
|---|---|---|
GET /api/v2/addons/trading-venue-desk-limits | v2AddonsTradingVenueDeskLimitsList | Desk trading-limit records and their maker-checker states, paginated. |
POST /api/v2/addons/trading-venue-desk-limits | v2AddonsTradingVenueDeskLimitsPropose | Proposes a desk limit for a trader wallet. Only approved records enforce at intake. |
POST /api/v2/addons/trading-venue-desk-limit-decisions | v2AddonsTradingVenueDeskLimitsDecide | Approves or rejects a proposal as a distinct operator. |
Error handling
Every error response carries a stable DALP-#### id and the error name; branch on them and see the error index for the full catalog with per-id guidance. The venue's own errors:
| Error | HTTP | When | Caller response |
|---|---|---|---|
ORDER_INTAKE_REJECTED | 422 | An intake check failed: eligibility, desk limits, trading authorization, fee cap, expiry, signature, submission rate, session state, participant list, a price band, or a size threshold. Nothing was accepted. | Correct the named check. Do not retry unchanged. |
RESERVATION_BUDGET_EXCEEDED | 409 | The wallet's cumulative reserved balance plus this order would exceed its spendable balance. | Cancel resting orders or submit a smaller order. |
RESERVATION_FAILED | 503 | The reserved-balance transaction reverted or timed out; the order was rejected and compensated. | Check the wallet balance and the venue's custodian role, then submit a new order. |
TRADING_VENUE_MARKET_NOT_FOUND | 404 | The market id does not name a market the caller can see in the active organization. Private markets answer this shape for non-members. | Use a market id from the markets list. |
TRADING_VENUE_ORDER_NOT_FOUND | 404 | The order id does not name an order the selected participant controls. | Use an order id from the working-orders list. |
TRADING_VENUE_ORDER_NOT_OPEN | 409 | The order already reached a terminal status; nothing was cancelled. | Refresh the working-orders list before retrying. |
TRADING_VENUE_OPERATOR_REQUIRED | 403 | The caller lacks the venue-operator role an administration route requires. | Sign in as a platform administrator or organization owner. |
MARKET_STATE_INVALID | 409 | The requested transition or setting is not valid for the market's current state, immutable-field changes included. | Check the market status and issue a valid request. |
MARKET_STREAM_NOT_FOUND | 404 | The stream request named a market this deployment does not serve, or came from another origin. | Open the stream same-origin against a live market id. |
TRADING_VENUE_NOT_FOUND | 404 | The venue address does not name a venue of the active organization. | Use a venue address from the venues list. |
TRADING_VENUE_FACTORY_UNAVAILABLE | 409 | No indexed Trading Venue factory exists yet for the system. | Wait for addon indexing, or register the addon factory first. |
TRADING_VENUE_TRADE_NOT_FOUND | 404 | The trade id does not name a trade on a market of the active organization. | Use a trade id from the market's trades list. |
TRADE_BUST_REFUSED | 422 | The bust pre-check failed at proposal or approval: settlement confirmation, order closure, the bust window, counterparty balances, or compliance path. Nothing was recorded or executed. | Resolve the named reason, then propose again. |
TRADE_BUST_APPROVAL_INVALID | 409 | The decision violated maker-checker: the proposer decided their own record, or the record was already decided. | Have a distinct operator decide, or refresh the approvals list. |
TRADE_BUST_EXECUTION_FAILED | 503 | The compensating reversal did not complete; no reversal leg remains applied and the record is marked failed. | Resolve the underlying cause and propose the bust again. |
TRADING_VENUE_APPROVAL_NOT_FOUND | 404 | The approval id does not name a maker-checker record in the active organization. | Use an approval id from the approvals or desk-limits list. |
TRADING_VENUE_WATCHLIST_NOT_FOUND | 404 | The watchlist id does not name a watchlist the authenticated user owns. | Use a watchlist id from your own watchlists list. |
Related
- Place and cancel orders for the signing walkthrough with full request and response examples.
- Trade through sessions and auctions for session state, calendars, and the indicative price.
- Place stop orders and use time in force for the stop and expiry contract.
- Quote in bulk for batch semantics and net-delta reservations.
- Read market data and streams for read and stream examples.
- Trading Venue capability for the architecture behind these routes.
- Request headers for participant selection and async preferences.
XvP settlement API and CLI flow
Create, approve, execute, and monitor XvP settlement flows through DALP APIs, SDKs, CLI commands, and polling.
Airdrop distribution reads
List and read deployed airdrop distributions through the DALP Platform API, SDK, and CLI, with filtering, pagination, recipient counts, and error codes.