Persist the shared cursor only after snapshotIndex equals snapshotCount.
LOADING
LOADING
API DOCUMENTATION
Stream orderbooks, query market history and submit wallet-signed limit orders through the same API used by the web application.
01 / QUICKSTART
Start with the deployment resource. It publishes the audience, validator addresses, fee parameters and current Head identity. Settlement integers use base-10 strings.
curl --fail --show-error \
https://api-preprod.boltsfinance.org/v1/deploymentPrices, amounts, fees, nonces, slots and snapshot numbers are JSON strings. Parse them with decimal-string or bigint logic; never binary floating point.
02 / REST RESOURCES
Public reads project authoritative confirmed state. Identity and private routes exist only when their gateway configuration is enabled.
/healthzFail-closed operational probe. Returns 503 until confirmed parameter state is valid.
Public/v1/deploymentNetwork, audience, scripts, fees, authentication window and Head state.
Public/v1/fee-tiersConfirmed $BOLTS balance tiers and 30-day volume multipliers from the parameter UTxO.
Public/v1/marketsConfigured pairs, explicit assets, decimals, pause state and open-order count.
Public/v1/markets/{marketId}/book?depth=NAggregated confirmed bids and asks with the state cursor and snapshot number.
Public/v1/market-summaries?window=24h&after=…&limit=…Keyset-paged 24-hour statistics with same-cursor bid, ask, spread and complete-book bid/ask/total base depth for market lists and selectors.
Public/v1/markets/{marketId}/trades?before=…&limit=…Cursor-page confirmed fills ordered newest first.
Public/v1/markets/{marketId}/candles?interval=…&from=…&to=…Bounded ascending confirmed OHLCV candles for supported intervals.
Public03 / CLIENTS & FEE TIERS
REST and WebSocket API v1 are the public integration contract. Raw HTTP and WebSocket clients are fully supported; no website-only backend exists.
@boltsdex/client-core is the framework-neutral TypeScript reference client used by this website in browsers and Node.js. It provides strict decoding, cursor handling, request signing and book-stream recovery, but it is currently a private workspace package at version 0.0.0, not a published npm SDK. Do not depend on it as a versioned external package yet.
GET /v1/fee-tiers decodes every balance and 30-day volume tier from the confirmed beacon-authenticated parameter output. Clients should fetch this resource and must not copy tier constants into their UI.
{
"requestId": "000000000000000018c41935e98cb3cf-00000000000000b4",
"confirmedCursor": "6af88318cbe6930348c385498dfe5d84b4091a6d031ff51ede1168b445d68613",
"baseFeeBps": "10",
"feeFloorBps": "2",
"boltsAsset": null,
"balanceTiers": [
{
"name": "Regular",
"minimumBolts": "0",
"discountBps": "0"
}
],
"volumeTiers": [
{
"minimumThirtyDayVolume": "0",
"multiplierBps": "10000"
}
]
}04 / API IDENTITY
Generate a 32-byte Ed25519 public/private keypair on the client. The wallet and API key sign the exact challenge bytes returned by the gateway. Do not parse or reconstruct that challenge.
Generate the API key locally.
Request a registration challenge for the full Shelley address.
Sign the challenge with CIP-30 signData and the API key.
Complete registration and retain the opaque identityId.
{
"kind": "registration",
"address": "addr_test1…",
"apiPublicKey": "<base64url-32-bytes>"
}The API key can authenticate a prepare request, but it cannot spend an order. Placement and cancellation still require the Cardano payment-key transaction witness checked by the gateway and ledger.
Manage this browser's API identity →05 / REQUEST SIGNING
Authenticated requests carry the identity, timestamp, random nonce, SHA-256 body digest and Ed25519 signature. Mutations also require a 16–32 byte base64url idempotency key.
boltsdex-request-v1
<audience>
<identityId>
<unix-ms>
<base64url-nonce>
POST
/v1/orders/prepare
<lowercase-body-sha256>
<base64url-idempotency-key>BoltsDEX-Identity: <identityId>
BoltsDEX-Timestamp: <unix-ms>
BoltsDEX-Nonce: <base64url-16..32-bytes>
BoltsDEX-Content-SHA256: <lowercase-hex>
BoltsDEX-Signature: <base64url-ed25519>
Idempotency-Key: <base64url-16..32-bytes>The target is canonical origin-form. Path and query use RFC 3986 encoding, query pairs sort bytewise, duplicate keys are rejected, and + is never a space alias. Retries reuse the body and idempotency key but use a fresh timestamp, nonce and signature.
06 / PLACE AN ORDER
Values in the prepare body use the market's human decimal precision. Funding references must be distinct, confirmed plain outputs belonging to the identity.
{
"marketId": "ada-usdcx",
"side": "sell",
"amount": "10",
"price": "2",
"minFill": "1",
"payoutAddress": "addr_test1…",
"inputReferences": ["<64-hex-tx-id>:0"]
}Prepare returns an intent, canonical atomic values and an Unwitnessed Tx ConwayEra envelope.
Check market, side, amount, price, minimum fill, expected transaction ID and intent expiry.
Ask the Cardano wallet to sign the exact returned Conway transaction locally.
Submit the full signed envelope and intent ID to POST /v1/orders.
The short intentExpiresAtMs only expires the prepared transaction and nonce reservation. Once confirmed, an order is GTC until filled or cancelled.
07 / CANCEL AN ORDER
Choose a distinct positive pure-ADA confirmed owner output as collateral, then use the same prepare/sign/submit discipline. Cancellation remains permitted while fills for a market are paused.
{
"collateralReference": "<64-hex-tx-id>:1"
}{
"intentId": "<returned-intent-id>",
"signedTransaction": {
"type": "Tx ConwayEra",
"description": "wallet-signed cancellation",
"cborHex": "<complete-signed-cbor>",
"txId": "<expected-transaction-id>"
}
}A fill and cancellation can race. The first transaction included in a confirmed snapshot wins; keep the order visible while cancellation is only submitted.
08 / WEBSOCKET
GET /v1/wsBrowser-compatible upgrade with no custom headers. The first message is hello, followed by subscribed snapshots or retained deltas.
{
"type": "subscribe",
"marketIds": ["ada-usdcx"],
"cursor": null
}{
"type": "book.delta",
"streamEpoch": "<epoch>",
"sequence": "43",
"cursor": "<opaque>",
"confirmedCursor": "<state-digest>",
"marketId": "ada-usdcx",
"bids": [],
"asks": [{"price":"80","amount":"0","orderCount":"0"}]
}Persist the shared cursor only after snapshotIndex equals snapshotCount.
A delta level whose amount and order count are both "0" deletes that level.
On resync.required, discard the derived book, fetch REST, then subscribe without the stale cursor.
Reply to every server ping with the same pingId in a pong.
09 / FINALITY
Exact transaction body pinned.
Owner witness added locally.
HTTP 202 / Hydra TxValid are pending.
Book and settled UI may advance.
10 / DEPLOYMENT & LIMITS
The REST base path is versioned independently from the request-signature domain. Clients must reject unknown response fields through the shared decoder and treat a future incompatible contract as a new API version.
Funding and open-order reads default to 50 records and accept a bounded limit from 1 to 100.
Challenge, registration and revocation JSON reject unknown fields and are capped at 16 KiB.
The hello message publishes maximum subscriptions, message bytes and heartbeat timing for that process.
Limits are deployment-specific. Honor standard limit headers, HTTP 429 and Retry-After; never retry in a tight loop.
Stable gateway errors include invalid_request, invalid_signature, replay_detected, rate_limited, market_paused, insufficient_funds, intent_expired, transaction_mismatch, stale_snapshot and submission_rejected. Every documented error envelope carries a request ID.
/v1/auth/challengesCreate a short-lived registration or revocation challenge.
/v1/auth/identitiesRegister a locally generated Ed25519 request key after both proofs verify.
Wallet proof/v1/auth/identities/{identityId}Revoke an identity with a fresh wallet-authorized challenge.
Wallet proof/v1/me/funding-utxos?after=…&limit=…Cursor-page confirmed plain outputs owned by the bound payment key.
Signed/v1/me/l1-utxosConfirmed plain Preprod L1 outputs at the identity's exact bound address; used only when a wallet connector returns an empty UTxO set.
Signed/v1/me/orders?state=open&after=…&limit=…Cursor-page current open order UTxOs; this endpoint does not infer history.
Signed/v1/orders/prepareReserve a venue nonce and return the exact unwitnessed placement transaction.
Signed/v1/ordersValidate and queue the complete wallet-signed prepared placement.
Signed/v1/orders/{outputReference}/cancel/preparePin an owner cancellation using a confirmed pure-ADA collateral output.
Signed/v1/orders/{outputReference}/cancelValidate and queue the complete wallet-signed cancellation.
SignedHistorical depth curves and operation-status reads are not part of the implemented public contract yet. There is no generic transaction submission or public Hydra lifecycle endpoint.