Persist the shared cursor only after snapshotIndex equals snapshotCount.
LOADING
LOADING
API DOCUMENTATION
Stream confirmed orderbooks and integrate the same wallet- or bot-signed trading and transfer flows used by the web application.
Your API deployment belongs to one trading pair and its Hydra Head. Fee tier and 30-day volume remain wallet-wide.
01 / QUICKSTART
Start with the market-Head catalog, choose a market, then read that Head's deployment resource. It publishes the audience, validator addresses, fee parameters, advertised order types and current Head identity. Settlement integers use base-10 strings.
curl --fail --show-error \
https://api-preprod.boltsfinance.org/v1/market-heads
curl --fail --show-error \
https://api-preprod.boltsfinance.org/markets/<marketId>/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. Except for the root catalog, the paths below are relative to /markets/{marketId}.
/healthzLightweight process and confirmed-parameter health probe.
Public/readyzReports only user-relevant trading, history and transfer capabilities. Internal database, recorder, provider and quota diagnostics remain on the private operator plane.
Public/v1/deploymentNetwork, audience, scripts, fees, authentication window and Head state.
Public/v1/market-headsRoot-level versioned catalog with one canonical gateway path per market.
Public/v1/assetsComplete bounded deployment catalog with exact identity, decimals, verified category and logo provenance.
Public/v1/valuationsApproximate display-only USD and EUR prices derived from the exact stablecoin anchor and sufficiently recent confirmed BoltsDEX VWAPs. Missing routes stay unavailable; external exchange prices never enter portfolio valuation.
Public/v1/deposits/pricesSelected-Head deposit minimum and exact pair-asset USD price evidence. Internal prices take priority; an allowlisted external fallback is admission-only. This read scans no wallet, reserves no deposit and consumes no transfer quota. Prepare rechecks prices and net principal; this is not a guaranteed quote.
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/sdk is the framework-neutral TypeScript implementation used by this website and BoltsBot, so transport, strict decoding, signing and stream recovery have one implementation in its own versioned repository. Version 0.1 is Apache-2.0 licensed but remains private and unpublished until the npm scope, hosted CI and provenance gates pass. Public users have full raw REST/WebSocket parity today; no private trading endpoint or operator-only matcher lane exists.
Market makers can subscribe to the same confirmed book stream and use the signed placement, amendment, cancellation and capability-gated batch routes from a headless process. The API key authenticates requests; every order transaction still needs the bot wallet's own Cardano signature. Protected Market takers can useexecuteMarketSweep to continue snapshot-confirmed rounds without a logical maker-count cap.
API identities are not transaction signers. Browser clients sign the transaction's explicit Cardano required-signer through CIP-30. The client signs one exact prepared transaction and never downloads historical producer transactions. Every discovered CIP-30 connector may attempt Hydra mutations; qualification still requires successful real Head-local-input tests for that wallet version. Headless bots keep their own Cardano signer. Optional Fast Trading uses a separate local delegate key for one explicitly allocated, pair-specific V2 state. It is the required signer only for value-conserving Manage transactions until expiry; it is neither an API identity nor a backend-held key. Economic strategy limits remain off-chain.
Asset identity and display metadata come from GET /v1/assets. ADA uses unit lovelace; Cardano native-token units concatenate the exact policy ID and asset name. Symbols and logos are presentation fields and must never select transaction assets.
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.
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 plus returned public paymentKeyHash.
The web app never opens this ownership prompt as a hidden side effect of loading an account page. An explicit protected action such as opening a deposit or withdrawal flow may authorize the browser in context and request one signData proof. It is not a transaction. The browser stops waiting after 60 seconds and lets the user retry; passive account-page reads do not wait on the wallet.
{
"kind": "registration",
"address": "<wallet-address>",
"apiPublicKey": "<base64url-32-bytes>"
}The API key can authenticate a prepare request, but it cannot spend an order. Placement, cancellation and transfers still require a separate Cardano transaction witness checked by the gateway and ledger. No transaction key is derived from or stored with this API identity.
API v1 deliberately has no client-selected CRUD scope matrix. Public market, fee, deployment and explorer reads need no key; owner data uses a signed identity; every mutation route is a fixed allowlisted operation and still needs the exact Cardano transaction witness where funds or orders change. An endpoint without a product use case is not published.
Review this browser's device access →A browser identity is non-extractable and stays in that browser. A headless market maker generates its API key and Cardano signer on its own host, completes the normal wallet-bound challenge, and gives the operator only its public payment key hash for rate-plan approval. The operator never creates, receives or recovers the private API key. Additional API identities for the same payment wallet share one Head-local budget. The 56-character payment key hash is the public hash of the Cardano payment verification key: it identifies the wallet but cannot sign a transaction or reveal its private key. Browser users can copy the exact registered value from the API identities settings page.
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. The gateway selects confirmed owner funding outputs and returns all unrelated assets and change to the bound payout owner. GTC defaults to post-only. When deployment discovery explicitly advertises marketable GTC, postOnly: false takes only at the limit or better and rests any final remainder at that exact limit. IOC, FOK and Market remain the non-resting alternatives.
{
"marketId": "ada-usdcx",
"side": "sell",
"amount": "10",
"price": "2",
"payoutAddress": "<wallet-address>"
}Prepare returns an intent, canonical atomic values and an Unwitnessed Tx ConwayEra envelope.
Check market, side, amount, price, the returned one-atom fill floor, 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 60-second intentExpiresAtMs only expires the prepared transaction and nonce reservation. Once confirmed, a post-only order or the final remainder of a marketable GTC stays open until filled or cancelled.
If deployment discovery publishes a positive maximumOrderBatchActions, one request may mix post-only placement, amendment and cancellation actions up to that bound. Version 1 requires at least one existing order and stays inside one market Head. Prepare and submit are the two outer API calls; each contained action uses one wallet admission unit in both phases.
07 / CANCEL AN ORDER
Send an empty prepare object. The gateway selects a distinct confirmed owner output, preferring pure ADA and preserving mixed native assets with an exact collateral return. Cancellation remains permitted while fills for a market are paused.
{}{
"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 / DEPOSIT & WITHDRAW
Deposit clients provide up to two canonical native pair assets plus one explicit gross ADA budget for one market Head; partial withdrawals use the same shape, while all=true is the bounded complete-exit path. The gateway selects bounded inputs and returns the exact transaction for local wallet review and signing.
Read the selected Head's settlement fees and static transfer buckets from GET /v1/deployment. When that deployment also publishes transferPolicy, signed GET /v1/me/rate-limits adds this wallet's live remaining counts and rolling reset times, and the net configured pair-asset principal must meet its advertised USD minimum from confirmed BoltsDEX valuations first and, only when explicitly advertised by that Head, the bounded admission-only fallback. The fee and technical ADA on a token/token Head do not count. A full all=true exit remains available after the partial withdrawal allowance reaches zero, but still uses authenticated burst limits, idempotency, one in-flight decommit and bounded non-empty balance checks. Fees use the published base + inputs + assets schedule, never an external price. Validate gross requestedAssets, the deducted ADA fee and net deposit/payout: entered token amounts never change, and no fee is added on top.
{
"assets": [{
"policyId": "",
"assetName": "",
"quantity": "5000000"
}]
}{
"assets": [{
"policyId": "",
"assetName": "",
"quantity": "5000000"
}]
}If no suitable whole Head output exists, withdrawal prepare can return stage: "split". Sign and submit that optimization, wait for its confirmed output, then prepare the final decommit. Never reuse an input reference across confirmed cursors.
To bundle wallet UTxOs without withdrawing, send only { "optimize": true }. The gateway combines two to eight compatible owner outputs into one zero-fee L2 output and waits for confirmed snapshot finality.
To withdraw every free asset together, send { "all": true } after cancelling open orders. Partial withdrawals preserve one shared ADA exit reserve; pure ADA dust below it is included automatically instead of being stranded.
A wallet-reported deposit hash is not L1 acceptance. A withdrawal submission is not an L1 payout. Poll and show the server lifecycle until the deposit is activated or the withdrawal is finalized, failed or marked for reconciliation. An expired deposit may become after the bounded recovery client asks Hydra to execute its official Recover path; the public API never accepts a raw recovery transaction.
09 / 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.
10 / FINALITY
Exact transaction body pinned.
Owner witness added locally.
HTTP 202 / Hydra TxValid are pending.
Book and settled UI may advance.
Order history advances only from confirmed snapshots. Deposit and withdrawal progress comes from the owner-scoped transfer journal; device-local receipts are continuity hints, never authoritative settlement state.
11 / DEPLOYMENT & LIMITS
The REST base path is versioned independently from the request-signature scope. Clients must validate response shapes 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.
trading.maximumOrderBatchActions is zero when unavailable and otherwise publishes the exact per-transaction action bound, never above ten.
Public reads and identity lifecycle use source budgets. Wallet identities share operation-specific prepare/submission buckets within each Head; provider budgets also include a daily wallet allowance across Heads. Read each published scope below. The bucket authentication_challenges covers challenge, registration and revocation. Only an operator-approved wallet receives the higher order/transfer profile, not more provider capacity. Honor HTTP 429 and Retry-After.
Limits could not be verified for the selected Head. Honor 429 and Retry-After; never substitute local rate values.
{
"error": {
"code": "invalid_request",
"message": "...",
"requestId": "...",
"details": {}
}
}/v1/fee-tiersConfirmed $BOLTS balance tiers and 30-day volume multipliers from the parameter UTxO.
/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={cursor}&limit={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/venue-summary?window=24hExact public DEX-transaction, trade and active-trader counts; pair, category and quote-asset volumes; and current Head TVL classified per asset. Unlike assets are never summed or assigned an unapproved USD value.
Public/v1/markets/{marketId}/trades?before={cursor}&limit={limit}Cursor-page confirmed fills ordered newest first.
Public/v1/markets/{marketId}/candles?interval={interval}&from={unixSeconds}&to={unixSeconds}Bounded ascending confirmed OHLCV candles for supported intervals.
Public/v1/explorer/trades?marketId={optional}&before={cursor}&limit={limit}Global or per-market confirmed fills with bounded keyset pagination.
Public/v1/explorer/transactions?marketId={optional}&before={cursor}&limit={limit}Privacy-bounded public order/trade transaction summaries.
Public/v1/explorer/snapshots?marketId={optional}&before={snapshot}&limit={limit}Confirmed snapshots containing public DEX activity; no owner or raw-CBOR data.
Public/v1/explorer/transfers?before={cursor}&limit={limit}Finalized deposits and withdrawals with exact assets, but no owner or address data.
Public/v1/explorer/strategy-events?marketId={optional}&before={cursor}&limit={limit}Confirmed Strategy V2 lifecycle events without owner identities or raw transaction data.
Public/v1/staking/historyLatest ten finalized epochs: global average eligible BOLTS and exact per-Head trading fees, allocations and carry. No wallet required; allocation is not payment.
Public/v1/explorer/staking-rewards?before={cursor}&limit={limit}Finality-only Staking payouts with exact recipient address, route, source epoch, Head, asset, output and transaction. Hydra payouts include a snapshot; Cardano payouts use L1 confirmation. Pending and failed attempts are never public.
Public/v1/auth/challengesCreate a short-lived registration or revocation challenge.
Wallet proof/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={cursor}&limit={limit}Cursor-page confirmed plain outputs owned by the bound payment key.
Signed/v1/me/l1-utxosConfirmed plain Cardano Preprod L1 outputs at the identity's exact bound address; used only when a wallet connector returns an empty UTxO set.
Signed/v1/me/fee-statusExact rolling 30-day quote volume split by maker and taker role, plus paid taker fees and the current direct personalized rate. The response includes the confirmed tier indices, normalized volume and exact rational rate.
Signed/v1/me/rate-limitsCurrent server-selected rate profile and exact wallet budgets for this market Head. Daily transfer buckets include live remaining counts and reset times. The client cannot request or select a profile.
Signed/v1/me/portfolio?range={range}Exact confirmed wallet, open-order and V2 strategy-locked balances plus optional internal display valuation and sparse rebuildable history.
Signed/v1/me/stakingCurrent opt-in state, liquid BOLTS stake, epoch time and boundary snapshot range plus the automatic-payout capability. Individual samples and cursors remain private.
Signed/v1/me/stakingEnable or disable liquid Staking with automatic L2 rewards with {"staked":true|false}. BOLTS never leave the owner's L1/L2 outputs or open orders.
/v1/me/staking/history?before={cursor}&limit={limit}Cursor-page completed epochs with personal and total stake averages plus exact per-Head reward assets and states. Only paid rewards contain their confirmed transaction, output, route-specific finality and time; there is no Claim route.
Signed/v1/me/transfers?kind={kind}&before={cursor}&limit={limit}Cursor-page deposit and withdrawal lifecycle records, including exact assets, change, deadlines, failures and L1 confirmation fields.
Signed/v1/me/orders?state=open&after={cursor}&limit={limit}Cursor-page current open order UTxOs; this endpoint does not infer history.
Signed/v1/me/order-history?marketId={marketId}&before={cursor}&limit={limit}Cursor-page confirmed placement, fill and cancellation lifecycle events.
Signed/v1/me/trade-history?marketId={marketId}&before={cursor}&limit={limit}Cursor-page confirmed owner fills with maker/taker role and exact fee amount.
Signed/v1/orders/prepareReserve a venue nonce for 60 seconds and return the exact unwitnessed GTC transaction. postOnly=true rejects a cross; capability-gatedpostOnly=false takes at the limit or better and rests only the confirmed terminal remainder.
/v1/ordersValidate and queue the complete wallet-signed prepared placement.
Signed/v1/orders/immediate/prepareSelect the deployment-bounded best makers and prepare an exact IOC, FOK or protected Market round. The website and bots continue confirmed Market rounds with the original limit through the same SDK path.
Signed/v1/orders/immediateValidate and queue only the complete wallet-signed immediate transaction.
Signed/v1/orders/batch/prepareCapability-gated API/bot path that atomically prepares up to ten same-owner, same-pair post-only place, amend and cancel actions. V1 requires at least one existing order to be consumed.
Signed/v1/orders/batchValidate and queue the one wallet-signed atomic batch. This reduces signing overhead but does not bypass per-action rate limits or increase Head capacity.
Signed/v1/orders/{outputReference}/cancel/prepareLet the gateway select collateral and pin the exact owner cancellation.
Signed/v1/orders/{outputReference}/cancelValidate and queue the complete wallet-signed cancellation.
Signed/v1/orders/{outputReference}/amend/preparePrepare one atomic owner-authorized replacement with a new amount, price, automatically assigned one-atom fill floor and time priority.
Signed/v1/orders/{outputReference}/amendValidate and queue the complete wallet-signed atomic replacement.
Signed/v1/deposits/prepareSelect safe owner L1 inputs for up to two native assets plus an explicit gross ADA budget in one market Head, deduct the exact ADA fee, allocate the missing shared reserve from net ADA, preserve unrelated assets as wallet change and return Hydra's exact commit transaction.
Signed/v1/depositsVerify the exact wallet-signed deposit body and owner witness, then submit the unchanged transaction through the gateway's Cardano L1 provider.
Signed/v1/withdrawals/prepareSelect confirmed Head inputs for up to two native pair assets plus a gross ADA budget, or use the complete balance for an exit, then return either a reserve-preserving split or the exact net unsigned decommit transaction.
Signed/v1/withdrawalsValidate and queue the complete wallet-signed decommit transaction.
Signed/v1/me/strategies?role={role}&after={cursor}&limit={limit}Read only V2 states for which the authenticated identity is the owner or delegate.
Signed/v1/strategies/allocations/preparePrepare one pair-specific state with owner, delegate, finite expiry and exact assets.
Signed/v1/strategies/allocationsSubmit only the exact allocation signed by the Main Wallet.
Signed/v1/strategies/{outputReference}/manage/preparePrepare a delegate transition that conserves the state's exact value and pair.
Signed/v1/strategies/{outputReference}/manageSubmit only the exact delegate-signed transition.
Signed/v1/strategies/{outputReference}/recover/prepareReturn the complete current state to its owner, even if delegate data is unusable.
Signed/v1/strategies/{outputReference}/recoverSubmit only the exact owner-signed recovery.
SignedThese routes are capability-gated and are not a generic transaction relay. The delegate cannot directly withdraw, change the owner or escape the pair, but it has no on-chain side, price or size limit and can economically lose the complete allocation through bad trades before expiry. See the custody and risk boundary before use.
Historical depth curves and generic operation-status reads are not part of the implemented public contract yet. Transfer lifecycle is available only through the owner-scoped transfer history. There is no generic transaction submission or public Hydra lifecycle endpoint.
GET /v1/me/transfers Returned to L1Every error carries a stable machine-readable code and request ID. Treat messages as explanatory text, honor Retry-After on HTTP 429 and derive exact limits from the active deployment above.