HTTP API
Every route of Hadal's HTTP API with its parameters, response fields, status values and errors.
The HTTP API serves what the chain shows about Hadal (markets, soundings, public events) and each wallet's sealed records as ciphertext. It also relays signed transactions and reports the computations they queue. Every path below is relative to the API's base URL. Requests and responses are JSON, except the event stream.
Conventions
Access and wallet parameters
The API has no sign-in, no key and no session. A wallet in a path or a viewer in a query is a public address used as a filter. It proves nothing about who is asking, and it authorizes nothing on chain. What a wallet's routes return is ciphertext that only the wallet's reading key opens.
Value types
These types are used by every route. Times are UTC.
| Type | JSON | Meaning |
|---|---|---|
Timestamp | integer | Milliseconds since the Unix epoch, UTC. Every time field, asOf included, has this type. |
Slot | integer | A Solana slot number. |
Address | string | A base58 address of 32 bytes: a wallet, mint, program or account. |
Signature | string | A base58 transaction signature of 64 bytes. |
MarketId | string | The address of the market's Market account. A market's id and its address field hold the same value. |
EntityId | string | The id of an order, deal, transfer, receipt, event or computation: 1 to 128 characters of letters, digits, underscore and hyphen. Which value it is for each record is told below. |
BaseUnits | string | An unsigned integer written as a decimal string, counted in atoms of a token. Do arithmetic on it with BigInt. |
DecimalString | string | A non-negative decimal number written as a string, for display. |
| Record | Its id | Meaning |
|---|---|---|
Market | Address | The Market account. |
Order | Address | The Order account. |
Deal | Address | The Deal account. It is the id in a deal's link. |
Computation | Address | The computation account on Arcium. |
Transfer, receipt, event | signature_n | The signature of the transaction that produced it, an underscore, and the position of its event in that transaction. |
Amounts and prices
No amount or price is a JSON number. Each is an object holding the exact integer and a display string. Atoms and the price scale are told in Units.
An Amount:
| Name | Type | Meaning |
|---|---|---|
baseUnits | BaseUnits | The exact amount in atoms of its token. |
decimal | DecimalString | The same amount in whole tokens. |
An amount of a token uses that token's decimals. Volumes and fee estimates are counted in the market's quote token and use its decimals.
A Price:
| Name | Type | Meaning |
|---|---|---|
quoteUnits | BaseUnits | Numerator of the exact price: quote atoms. |
baseUnits | BaseUnits | Denominator: base atoms. For every price the API serves it is 4294967296 (2^32), so quoteUnits is the price as the program holds it. |
decimal | DecimalString | Quote tokens per one whole base token, to 18 decimals at most. |
The exact price is the ratio quoteUnits / baseUnits in quote atoms per base atom. quoteUnits is the value an instruction takes as a limit.
Sealed values
Every private value arrives as a Sealed object:
| Name | Type | Meaning |
|---|---|---|
sealed | true | Always true. Marks the object as ciphertext. |
ciphertexts | string[] | The ciphertexts, each the base64 of exactly 32 bytes. How many there are depends on the field, below. |
nonce | string | Base64 of exactly 16 bytes. |
encryptionKey | string | The x25519 public key of the owner's reading key: base64 of exactly 32 bytes. |
| Field | Ciphertexts | Decodes to |
|---|---|---|
Balance.values, Share.values, Receipt.values, Order.state | 4 | A ledger: the owner's base, quote and shares, and the receipt of the last action. Read it with the SDK's Sealer.ledger. |
Order.terms | 5 | The order's sealed input. Read it with Sealer.open. |
Deal.terms | 5 | The maker's sealed input. The deal's side is not in it: it is the public field side. Read it with Sealer.open. |
Deal.answer.terms | 4 | The taker's sealed input. It has four ciphertexts and is not a ledger. Read it with Sealer.open. |
The values each sealed input holds, in order, are in Sealed input shapes. What a ledger and its receipt decode to is in Ledger and Receipt. Decode ciphertexts and nonce from base64 to bytes before handing them to the SDK.
The API never receives a reading key and never decrypts. An order's side, size and limit, a fill, a receipt's result and a balance exist in its responses only inside these objects. Decrypting them is done by the wallet's owner: see The reading key.
Pagination
Every route that returns a list takes two query parameters and returns the same wrapper.
| Parameter | Type | Meaning |
|---|---|---|
limit | integer | Items per response, 1 to 100. Default 24. |
cursor | string | Where the response starts. Omit it for the start of the list, then pass the page.nextCursor of the previous response unchanged. |
| Field | Type | Meaning |
|---|---|---|
items | array | The records of this response. |
page.nextCursor | string | null | The cursor of the next response, or null at the end of the list. |
page.hasMore | boolean | Whether more records follow. |
asOf | Timestamp | When the response was read. |
freshness | 'live' | 'stale' | See Freshness below. |
error | ApiError | null | See Freshness below. |
A route accepts only the query parameters listed for it. Any other parameter is answered with VALIDATION_ERROR. A market query that names a market the API has not indexed is answered with NOT_FOUND.
Freshness and asOf
Every list, the totals and the portfolio carry asOf, freshness and error. asOf is the time the data was read. freshness is live and error is null when that reading is current. A response marked stale holds an earlier reading, with the error envelope that explains why in error and the code at error.error.code.
While GET /health says waiting, every list is empty and the totals are zero.
Errors
A failed request answers with this body:
| Field | Type | Meaning |
|---|---|---|
error.code | string | The stable code to branch on. All codes are in the table at the end of this page. |
error.message | string | One sentence that can be shown to a person. |
error.retryable | boolean | Whether sending the same request again can succeed. |
error.stage | string | Where the flow failed: validation, auth, read, upload, build, wallet, co_sign, simulation, send or confirmation. |
error.fieldErrors | object, optional | On VALIDATION_ERROR: field path to a list of messages. A message about the request as a whole is under the key form. |
error.programError | object, optional | On CHAIN_REFUSED: programId (Address), name and number of the error of the program that refused. |
error.retryAfterSeconds | integer, optional | On RATE_LIMITED: seconds until the request can be sent again. The Retry-After header carries the same value. |
Branch on error.code, never on the message. Retry only when error.retryable is true. The same envelope appears as a value inside successful responses, in the error field of a transaction and a computation: there the code is at error.error.code.
The names and numbers a programError can carry for the Hadal program are in the program's errors.
Every route can answer VALIDATION_ERROR, ORIGIN_NOT_ALLOWED and INTERNAL_ERROR. A path that is not a route answers NOT_FOUND. The sections below name what each route adds.
Response headers
Every response carries X-Request-Id, a unique id for the request, and X-Contract-Version, the version of the API's contract. The request id is in this header only, never in an error's body: quote it when reporting a failure. GET /health returns the contract version in its body too.
Write limits
POST /v1/transactions is limited to 60 requests per client per minute, counted in fixed one-minute windows. The request over the limit answers RATE_LIMITED with retryAfterSeconds. A request body is at most 65536 bytes, beyond which the answer is PAYLOAD_TOO_LARGE. The body must be sent with Content-Type: application/json, or the answer is UNSUPPORTED_MEDIA_TYPE. GET requests under /v1 are not limited. POST /rpc has its own limit.
Routes
| Route | Returns | Use |
|---|---|---|
GET /health | Service status | Whether the API has found the program on chain, the contract version it speaks and its clock. |
GET /openapi.json | OpenAPI 3.1 document | Every route, parameter, response schema and error status in machine-readable form. |
GET /v1/markets | Page of markets | Every open market with its address, tokens, last public price and 24-hour volumes. |
GET /v1/markets/:market | Market | One market by its address. |
GET /v1/markets/:market/config | Market config | The program, accounts, vaults, token programs, lookup table, cluster, fee rates and RPC URL a client needs to build transactions for a market. |
GET /v1/soundings | Page of soundings | Soundings of all markets, newest first, with an optional market filter. |
GET /v1/markets/:market/soundings | Page of soundings | One market's soundings, oldest first. |
GET /v1/markets/:market/candles | Page of candles | Open, high, low, close and volumes per interval, aggregated from the market's soundings, oldest first. |
GET /v1/markets/:market/fees | Page of fee payouts | The protocol fees a market has paid out, in both of its tokens, newest first. |
GET /v1/pools | Page of markets | The same markets as GET /v1/markets, read for their pool's volumes and fee estimate. |
GET /v1/totals | Totals | Volume and paid protocol fees to date grouped by mint, the sounding count, and HADAL bought and burned. |
GET /v1/events | Page of public events | The public events of all wallets, newest first. |
GET /v1/events/stream | Server-sent events | Public events as they are indexed, with ready and resync messages. |
GET /v1/wallets/:wallet/balances | Page of sealed balances | The wallet's sealed ledger in each market, read from the chain. |
GET /v1/wallets/:wallet/shares | Page of liquidity shares | The same sealed ledgers, each with the wallet's latest liquidity computation. |
GET /v1/wallets/:wallet/orders | Page of orders | The wallet's orders with public kind, status and queue position, sealed terms and latest receipt, newest first. |
GET /v1/wallets/:wallet/receipts | Page of receipts | Every sealed ledger the wallet's actions produced, each with its public kind, account and time, newest first. |
GET /v1/wallets/:wallet/deals | Page of deals | The deals the wallet made, is named in or has answered, newest first. |
GET /v1/wallets/:wallet/transfers | Page of transfers | The wallet's deposits and withdrawals with their status, newest first. |
GET /v1/wallets/:wallet/portfolio | Portfolio | Everything the wallet holds in one response: balances, shares, orders, deals, receipts and transfers, each list whole. |
GET /v1/orders/:id | Order | One order by the address of its Order account. |
GET /v1/deals/:id | Deal | One deal by the address of its Deal account, presented for the wallet passed as viewer. |
GET /v1/transfers/:id | Transfer | One deposit or withdrawal by id. |
POST /v1/transactions | Transaction | Checks, simulates and broadcasts a transaction the wallet has signed, and returns the record to follow. |
GET /v1/transactions/:signature | Transaction | The status of a relayed transaction by its signature. |
GET /v1/computations/:id | Computation | One computation by its account's address, or the latest computation of an order, deal, balance or market. |
POST /rpc | JSON-RPC response | Relays one read or simulate call to the cluster's Solana RPC. It does not relay sendTransaction. |
Service
GET /health
GET /health| Field | Type | Meaning |
|---|---|---|
status | string | waiting or ready. Below. |
contractVersion | string | The version of the contract the API speaks. |
time | Timestamp | The API's clock. |
| Status | Meaning |
|---|---|
ready | The API has found the Hadal program and its Config account on chain. Every route serves. |
waiting | It has not found them yet. Lists are empty, a read of one record and both transaction routes answer PROGRAM_UNAVAILABLE. The API turns ready by itself. |
GET /openapi.json
GET /openapi.jsonReturns the OpenAPI 3.1 document of this API: every route here with its parameters, the JSON Schema of each response and the statuses an error can arrive with.
Markets and soundings
:market in a path, and market in a query, is the address of a market.
GET /v1/markets
GET /v1/markets?limit=24The markets that are open for trading, ordered by address.
| Query | Type | Meaning |
|---|---|---|
market | MarketId | Optional. Return only this market. |
limit | integer | Default 24, maximum 100. |
cursor | string | From page.nextCursor. |
Returns a page whose items are Market objects:
| Field | Type | Meaning |
|---|---|---|
id | MarketId | The market. |
address | Address | The Market account. The same value as id. |
ready | boolean | Whether the market is open for trading. |
base | Token | The base token: symbol (string), mint (Address), decimals (integer). symbol holds the mint address when the API knows no symbol for the mint. |
quote | Token | The quote token, same three fields. |
price | Price | The market's last public price. priceSource says where it comes from. |
priceSource | string | sounding, account_snapshot or first_liquidity. Below. |
priceAt | Timestamp | Time of the last sounding the API holds, or of its last reading of the market when it holds none. |
slot | Slot | Slot of the last sounding, or of the reading. |
crossed24h | Amount | Volume crossed in the book over the last 24 hours, in the quote token. |
swept24h | Amount | Volume swept from the pool over the last 24 hours, in the quote token. |
lpFeesLastSoundingEstimate | Amount | null | An estimate of the sweep fees the pool's liquidity providers earned in the last sounding's period, in the quote token. Computed as for a sounding's lpFeeEstimate. null while the protocol's share is not set. |
change24h | string | Price change as a signed decimal fraction of the earlier price: 0.01 is 1%. The earlier price is the latest sounding at least 24 hours old, or the market's first price when there is none. |
| priceSource | Meaning |
|---|---|
sounding | The price of the last sounding the API holds. |
account_snapshot | The last sounding price stored on the Market account. The API holds no sounding record for it. |
first_liquidity | The market has not been sounded: the price its first liquidity was added at. |
GET /v1/markets/:market
GET /v1/markets/:marketReturns one Market object, with the fields of GET /v1/markets.
Errors: NOT_FOUND when the API has not indexed a market with this address, PROGRAM_UNAVAILABLE.
GET /v1/markets/:market/config
GET /v1/markets/:market/configReturns what a client needs to build transactions for the market. The rates and parameters are read from the program's Config account at the time of the request.
| Field | Type | Meaning |
|---|---|---|
market | Market | The market, as in GET /v1/markets. |
programId | Address | The Hadal program. |
configAccount | Address | The program's Config account. |
marketAccount | Address | The market's account. |
baseVault | Address | The vault that holds the base token. |
quoteVault | Address | The vault that holds the quote token. |
baseTokenProgram | Address | The token program of the base mint. |
quoteTokenProgram | Address | The token program of the quote mint. |
lookupTable | Address | The address lookup table for the market's transactions. |
arciumClusterOffset | integer | The Arcium cluster the program computes on. |
rpcUrl | string | The URL of this API's POST /rpc, for a web3.js Connection. |
priceScale | BaseUnits | The scale of every price and limit: 4294967296. |
soundingIntervalSlots | integer | Slots between two soundings. |
fees.sweepBps | integer | The sweep fee in basis points. |
fees.crossBpsPerSide | integer | The cross fee each side pays, in basis points. |
fees.dealBpsPerSide | integer | The deal fee each side pays, in basis points. |
fees.protocolShareOfSweepBps | integer | The protocol's share of the sweep fee, in basis points of that fee, 0 to 10000. |
defaultDealAttempts | integer | Attempts each taker gets on a deal when the maker sets no other number. |
feeRecipient | Address | The wallet that receives protocol fees. |
hadalMint | Address | null | The mint of HADAL. null while not set. |
The fee rates are told in Fees.
Errors: NOT_FOUND, PROGRAM_UNAVAILABLE, and CONFIGURATION_REQUIRED while the protocol's share of the sweep fee or the lookup table is not set.
GET /v1/soundings
GET /v1/soundings?market=:market&from=:ms&to=:msSoundings of all markets, newest first.
| Query | Type | Meaning |
|---|---|---|
market | MarketId | Optional. Only this market. |
from | Timestamp | Optional. Only soundings at or after this time. |
to | Timestamp | Optional. Only soundings at or before this time. |
limit | integer | Default 24, maximum 100. |
cursor | string | From page.nextCursor. |
Returns a page whose items are Sounding objects:
| Field | Type | Meaning |
|---|---|---|
market | MarketId | The market sounded. |
slot | Slot | The slot of the sounding. |
time | Timestamp | Its time. |
price | Price | The pool's price. |
crossed | Amount | Volume crossed in the book since the previous sounding, in the quote token. |
swept | Amount | Volume swept from the pool since the previous sounding, in the quote token. |
protocolFeeBase | Amount | Protocol fee of the period taken in the base token, in base atoms. Exact. |
protocolFeeQuote | Amount | Protocol fee of the period taken in the quote token, in quote atoms. Exact. |
protocolFee | Amount | The same value as protocolFeeQuote. The base part is not converted into it. |
lpFeeEstimate | Amount | null | An estimate of the sweep fees the pool's liquidity providers earned in the period, in quote atoms. Below. null while the protocol's share is not set. |
signature | Signature | The transaction that put the sounding on chain. |
The protocol fee is reported in both tokens and the two amounts are never added together. Which token a fee is taken in is told in Protocol fees.
lpFeeEstimate is computed from the public swept volume, not measured from fills, which are sealed:
floor(swept * sweepBps * (10000 - protocolShareOfSweepBps) / 100000000)It uses the protocol's share as it is set at the time of the request.
What a sounding is and why it is the only trading data on the surface: Soundings.
GET /v1/markets/:market/soundings
GET /v1/markets/:market/soundings?from=:ms&to=:msOne market's soundings in time order, oldest first. Query: from, to, limit, cursor, as in GET /v1/soundings. A market query parameter is rejected here: the market is in the path. Returns a page of Sounding objects.
Errors: NOT_FOUND, PROGRAM_UNAVAILABLE.
GET /v1/markets/:market/candles
GET /v1/markets/:market/candles?interval=5mCandles of one market, oldest first. A candle aggregates the soundings whose time falls in its interval. It holds no individual fill.
| Query | Type | Meaning |
|---|---|---|
interval | string | One of 1m, 5m, 15m, 1h, 1d. Default 5m. |
from | Timestamp | Optional. Only candles that start at or after this time. |
to | Timestamp | Optional. Only candles that start at or before this time. |
limit | integer | Default 24, maximum 100. |
cursor | string | From page.nextCursor. |
Returns a page whose items are Candle objects:
| Field | Type | Meaning |
|---|---|---|
market | MarketId | The market. |
interval | string | The interval asked for. |
time | Timestamp | Start of the interval. |
open | Price | Price of the first sounding in the interval. |
high | Price | Highest sounding price in the interval. |
low | Price | Lowest sounding price in the interval. |
close | Price | Price of the last sounding in the interval. |
crossed | Amount | Sum of the soundings' crossed volume, in the quote token. |
swept | Amount | Sum of the soundings' swept volume, in the quote token. |
soundings | integer | How many soundings the candle aggregates. At least 1. |
Errors: NOT_FOUND, PROGRAM_UNAVAILABLE.
GET /v1/markets/:market/fees
GET /v1/markets/:market/fees?from=:ms&to=:msThe protocol fees the market has paid out to the fee recipient, newest first. A sounding reports fees as they accrue. A payout is the transfer that pays them. Query: from, to, limit, cursor.
Returns a page whose items are FeePayout objects:
| Field | Type | Meaning |
|---|---|---|
market | MarketId | The market. |
time | Timestamp | When the payout was made. |
slot | Slot | Its slot. |
base | Amount | Base token paid out. |
quote | Amount | Quote token paid out. |
signature | Signature | The transaction. |
Errors: NOT_FOUND, PROGRAM_UNAVAILABLE.
GET /v1/pools
GET /v1/poolsQuery: market, limit, cursor. Returns a page of Market objects, the same as GET /v1/markets. For a pool, read crossed24h, swept24h and lpFeesLastSoundingEstimate. A pool's reserves are sealed and are in no response.
GET /v1/totals
GET /v1/totalsTakes no query parameters.
| Field | Type | Meaning |
|---|---|---|
volume | array | Volume of all soundings the API holds, crossed and swept together, one entry per quote mint: mint (Address) and amount (Amount). |
fees | array | Protocol fees paid out to date, one entry per mint, base and quote mints alike: mint (Address) and amount (Amount). |
soundings | integer | How many soundings the API holds. |
hadal.mint | Address | null | The mint of HADAL. null while not set. |
hadal.status | string | mint_not_set while hadal.mint is null, active once it is set. |
hadal.bought | Amount | HADAL bought with protocol fees to date. |
hadal.burned | Amount | HADAL burned to date. |
asOf | Timestamp | When the totals were read. |
freshness | 'live' | 'stale' | As for a list. |
error | ApiError | null | As for a list. |
Amounts of different mints are never added together. What the fees buy is told in The token.
Public events
GET /v1/events
GET /v1/events?market=:marketWhat the surface shows wallets doing, newest first. Query: market (optional MarketId), limit, cursor. Returns a page whose items are PublicEvent objects:
| Field | Type | Meaning |
|---|---|---|
id | EntityId | The event. |
kind | string | One of the six kinds below. |
time | Timestamp | The block time of its transaction. |
wallet | Address | The wallet that acted. |
market | MarketId | The market it acted in. |
signature | Signature | The transaction. |
amount | Amount | Only on deposit and withdraw: the amount. |
token | string | Only on deposit and withdraw: the symbol of the token, as in the market. |
paid | boolean | Only on withdraw: true when the tokens left the vault, false when the withdrawal was refused. |
| Kind | Meaning |
|---|---|
order_placed | The wallet placed a sealed order. Nothing about the order is in the event. |
deal_opened | The wallet opened a deal. |
deal_done | The wallet's answer to a deal traded. |
no_deal | The wallet's answer to a deal did not trade. |
deposit | The wallet sent amount of token to the vault. The event appears when the deposit is queued. |
withdraw | The withdrawal of amount of token finished. paid says whether it was paid or refused. |
Only deposit and withdraw carry amount and token. No event carries a side, a size, a limit, a fill or a receipt's result. What is sealed and what is seen lists it action by action.
GET /v1/events/stream
GET /v1/events/stream?market=:market
Accept: text/event-streamThe same public events as the API indexes them, as server-sent events. The only query parameter is market (optional MarketId), which keeps only that market's events. limit and cursor are rejected.
Each event is named by its type, and its data line is one JSON object:
| Field | Type | Meaning |
|---|---|---|
id | string | The id of the message, also sent as the SSE id. |
timestamp | Timestamp | When the message was sent. |
type | string | ready, public_event or resync. Also the SSE event name. |
data | object | Depends on type, below. |
| Type | data | Meaning |
|---|---|---|
ready | status | Sent first on every connection, and again whenever the status changes. status is waiting or ready, as in GET /health. Events follow only while it is ready. |
public_event | PublicEvent | One public event, with the fields of GET /v1/events. |
resync | reason | Events were missed. reason is reconnected when the connection was opened with a Last-Event-ID header. It is behind when the client read too slowly and its queue of 500 messages filled, or when the API could not read new events. |
The stream does not replay: a Last-Event-ID is answered with resync, not with the missed events. On resync, fetch GET /v1/events again and continue from the stream. The API looks for new events every 2 seconds. A comment line is sent every 15 seconds while no message occurs, to keep the connection open. Listen by event name: with EventSource, add a listener for public_event, ready and resync.
A wallet's sealed records
Each route here takes the wallet's address in the path and returns that wallet's records. :wallet is an Address. A wallet with no records gets an empty list, not an error. Each list takes market (optional MarketId), limit and cursor, and is ordered newest first.
GET /v1/wallets/:wallet/balances
GET /v1/wallets/:wallet/balancesThe wallet's Balance account in each open market, read from the chain at the time of the request, latest change first. Returns a page whose items are Balance objects:
| Field | Type | Meaning |
|---|---|---|
market | MarketId | The market. |
owner | Address | The wallet. |
values | Sealed | The sealed ledger, four ciphertexts: base, quote and shares held, and the receipt of the last action. |
layout | string | ledger-v1: values is a ledger. |
fresh | boolean | true until the first computation writes the ledger. A fresh balance holds nothing. |
updatedAt | Timestamp | When the API last saw the balance change. |
See Sealed balances.
GET /v1/wallets/:wallet/shares
GET /v1/wallets/:wallet/sharesA wallet's liquidity shares are the shares value of the same ledger. Returns a page whose items are Share objects: the fields of a Balance, plus
| Field | Type | Meaning |
|---|---|---|
computation | Computation | null | The wallet's latest liquidity computation in the market, as in GET /v1/computations/:id. null when it has none. |
See Liquidity.
GET /v1/wallets/:wallet/orders
GET /v1/wallets/:wallet/ordersReturns a page of Order objects, latest placed first, with the fields of GET /v1/orders/:id.
GET /v1/wallets/:wallet/receipts
GET /v1/wallets/:wallet/receiptsThe wallet's whole receipt history, newest first. Each time an action changes the wallet's sealed balance, the program emits the balance's new ledger. A receipt here is that ledger, kept as it was emitted, with the public facts of the action that produced it. Returns a page whose items are Receipt objects:
| Field | Type | Meaning |
|---|---|---|
id | EntityId | The receipt. |
owner | Address | The wallet it is encrypted to. |
market | MarketId | The market. |
kind | string | The action: order, deal, deposit, withdraw, liquidity, collect or cancel. Below. |
account | Address | The account acted on: orderId when it is set, otherwise dealId, otherwise balanceId. |
orderId | EntityId | null | The order. Set when the action was on an order. |
dealId | EntityId | null | The deal. Set when the action was on a deal. |
transferId | EntityId | null | The transfer. Set when the action finished a deposit or a withdrawal. |
balanceId | Address | The wallet's Balance account in the market. |
time | Timestamp | The block time of the transaction that emitted the ledger. |
slot | Slot | Its slot. |
signature | Signature | That transaction. |
values | Sealed | The sealed ledger, exactly four ciphertexts and their nonce: the balance after the action and the action's receipt. |
layout | string | ledger-v1: values is a ledger. |
| Kind | Id set | The ledger was emitted when |
|---|---|---|
order | orderId | The order was processed. |
collect | orderId | Proceeds of a resting order were collected. |
cancel | orderId or dealId | With orderId: the order was cancelled and settled. With dealId: the deal was closed and settled to its maker, with what was left of the escrow and the proceeds. |
deal | dealId | For the maker: the deal's opening landed. For a taker: the taker's answer was computed, whether it traded or not. |
deposit | transferId | A deposit landed or was refunded. |
withdraw | transferId | A withdrawal was paid or refused. |
liquidity | none | Liquidity was added or removed, or the market the wallet created was opened. account is the balance. |
An order's receipt has orderId, a deal's has dealId, a transfer's has transferId, and each has null in the other two. An order settled without the record of the call that settled it has kind order.
values is read with Sealer.ledger, passing ciphertexts and nonce as bytes. The result's receipt holds the action's figures, and ok false means the action moved nothing. See Read your receipts and, from a script, the script guide.
GET /v1/wallets/:wallet/deals
GET /v1/wallets/:wallet/dealsThe deals the wallet made, the deals that name it as counterparty and the deals it has answered, latest opened first, each presented with the wallet as viewer. Returns a page of Deal objects, with the fields of GET /v1/deals/:id.
GET /v1/wallets/:wallet/transfers
GET /v1/wallets/:wallet/transfersReturns a page of Transfer objects, newest first, with the fields of GET /v1/transfers/:id.
GET /v1/wallets/:wallet/portfolio
GET /v1/wallets/:wallet/portfolioEverything the routes above return, in one response. Each list is whole, not cut at a limit, and in the same order as its own route. Takes no query parameters.
| Field | Type | Meaning |
|---|---|---|
wallet | Address | The wallet asked for. |
balances | Balance[] | Its sealed balances. |
shares | Share[] | Its liquidity shares. |
orders | Order[] | Its orders. |
deals | Deal[] | Its deals as maker, as counterparty and as answerer. |
receipts | Receipt[] | Its whole receipt history. |
transfers | Transfer[] | Its deposits and withdrawals. |
asOf | Timestamp | When the portfolio was read. |
freshness | 'live' | 'stale' | As for a list. |
error | ApiError | null | As for a list. |
Orders
GET /v1/orders/:id
GET /v1/orders/:id:id is the address of the Order account. Returns one Order:
| Field | Type | Meaning |
|---|---|---|
id | EntityId | The order: the address of its Order account. |
owner | Address | The wallet that placed it. |
market | MarketId | The market. |
kind | string | swap or dark. Public. |
status | string | pending, resting or closed. Below. |
queue | integer | null | The order's position in the market's queue while it is pending: 1 is the next order processed. null otherwise. |
placedAt | Timestamp | When it was placed. |
expiry | Timestamp | null | When the order expires. null when it has no expiry. |
terms | Sealed | The sealed input, five ciphertexts. |
state | Sealed | A sealed ledger, four ciphertexts. stateSource says which. |
stateSource | string | order_receipt: the ledger stored on the order, which is the order's result. balance_snapshot: the order has no result yet, and state is the owner's current balance. |
stateLayout | string | ledger-v1: state is a ledger. |
receipt | Receipt | null | The order's latest receipt, as in GET /v1/wallets/:wallet/receipts: of kind order, collect or cancel. null until it has one. |
returnReason | integer | null | Why the order was returned without being processed. Below. null when it was not. |
computation | Computation | null | The latest computation queued for the order, as in GET /v1/computations/:id. null when none was queued. |
| Status | Meaning |
|---|---|
pending | The order is in the market's queue and has not been processed. queue holds its position. |
resting | A dark order was processed and size of it rests in the sealed book. |
closed | The order is finished: a processed swap, a processed dark order with nothing left to rest, a cancelled order, or an order returned unprocessed. What it filled is inside its sealed receipt. |
| returnReason | Meaning |
|---|---|
0 | The book was full: a dark order found no free slot. |
1 | The owner cancelled the order while it was pending. |
2 | The order reached the head of the queue after its expiry. |
3 | The owner's balance had another computation in flight when the order reached the head of the queue. |
For an order's result, read receipt, or state when stateSource is order_receipt. See Sealed orders.
Errors: NOT_FOUND when the API has not indexed an order with this address, PROGRAM_UNAVAILABLE.
Deals
GET /v1/deals/:id
GET /v1/deals/:id?viewer=:wallet:id is the address of the Deal account, the id a deal's link carries.
| Query | Type | Meaning |
|---|---|---|
viewer | Address | Optional. The wallet the deal is presented for. It decides access and which sealed fields are present. |
Returns one Deal:
| Field | Type | Meaning |
|---|---|---|
id | EntityId | The deal: the address of its Deal account. |
market | MarketId | The market. |
maker | Address | The wallet that opened it. |
taker | Address | null | The named counterparty. null when anyone holding the link can answer. |
side | string | The maker's side, public: buy when the maker buys the base token and a taker sells it, sell when the maker sells it. |
status | string | opening, open, done, cancelled, expired or void. Below. |
attempts | integer | Attempts each taker gets. |
attemptsUsed | integer | Attempts the viewer has used. 0 without a viewer. |
expiry | Timestamp | When the deal stops accepting answers. |
createdAt | Timestamp | When it was opened. |
viewer | Address | null | The viewer passed, or null. |
access | string | What the viewer is to the deal. Below. |
terms | Sealed | null | The maker's sealed input, five ciphertexts. Present only when access is maker. |
state | null | Always null. The deal's escrow is sealed to the cluster alone and no wallet key reads it. |
answer | object | null | The viewer's last answer. null when the viewer has no computed answer. |
answer.outcome | string | done when the answer traded, no_deal when it did not. |
answer.terms | Sealed | null | The viewer's own sealed input, four ciphertexts. |
answer.receipt | Receipt | null | The receipt of that answer, of kind deal, as in GET /v1/wallets/:wallet/receipts. |
receipt | Receipt | null | The viewer's latest receipt on this deal. For the maker it is the opening's receipt, then the settlement's once the deal is closed, which holds the totals. null without a viewer. |
computation | Computation | null | The latest computation queued for the deal, as in GET /v1/computations/:id. |
The status is the one on the Deal account. What each status means and what follows it is in Deals.
| Status | Meaning |
|---|---|
opening | The computation that takes the escrow has not landed. |
open | The deal takes answers. |
done | Its whole size traded. |
cancelled | The maker cancelled it and it is settled. |
expired | It passed its expiry and it is settled. |
void | The escrow was not taken. Nothing moved. |
| Access | Meaning |
|---|---|
maker | The viewer opened the deal. |
link | The deal names no counterparty: anyone holding its link can answer. |
counterparty | The viewer is the named counterparty. |
not_counterparty | The deal names a counterparty and the viewer is not it, or no viewer was passed. |
The maker's terms are never returned to a taker, sealed or not. access is a presentation of public facts: the program decides who can answer when the transaction arrives.
Errors: NOT_FOUND when the API has not indexed a deal with this address, PROGRAM_UNAVAILABLE.
Transfers
GET /v1/transfers/:id
GET /v1/transfers/:id:id is the transfer's id, from a wallet's transfers or a receipt's transferId. Returns one Transfer, a deposit or a withdrawal:
| Field | Type | Meaning |
|---|---|---|
id | EntityId | The transfer. |
kind | string | deposit or withdraw. |
status | string | Depends on kind. Below. |
owner | Address | The wallet. |
market | MarketId | The market whose vault the tokens enter or leave. |
token | string | The symbol of the token, as in the market. |
amount | Amount | The amount. Deposits and withdrawals are public. |
time | Timestamp | The block time of the transaction that queued it. |
signature | Signature | null | The transaction that finished the transfer, or the one that queued it while it is pending. |
computation | Computation | null | The computation that applies it to the sealed balance, as in GET /v1/computations/:id. |
error | ApiError | null | null. A refused withdrawal is told by status, and ok is false in its receipt. |
| Kind | Status | Meaning |
|---|---|---|
deposit | pending | The tokens are in the vault and the computation that adds them to the sealed balance has not landed. |
deposit | landed | The amount is in the sealed balance. |
deposit | refunded | The computation did not finish and the tokens went back to the wallet. |
withdraw | pending | The computation that checks the sealed balance has not landed. |
withdraw | paid | The tokens moved from the vault to the wallet. |
withdraw | refused | The sealed balance did not cover the amount and nothing moved. |
See Deposit and withdraw.
Errors: NOT_FOUND when the API has not indexed a transfer with this id, PROGRAM_UNAVAILABLE.
Transactions and computations
Every action on Hadal is a transaction the wallet signs. The API relays it, then reports two things in turn: the transaction's status on chain, and the computation it queued.
POST /v1/transactions
POST /v1/transactions
Content-Type: application/jsonRelays a transaction the wallet has already signed. The API adds no signature and changes no byte. The body:
| Field | Type | Meaning |
|---|---|---|
wallet | Address | The wallet that signed. It must be the fee payer of the transaction. |
transactionBase64 | string | The whole signed versioned transaction as canonical base64: at most 1232 bytes, 1644 characters. |
lastValidBlockHeight | integer | The last block height at which the transaction is valid, as returned with the blockhash it was built on. Greater than zero. |
The body takes these three fields and no others. The relay accepts a transaction when all of this holds:
- The wallet is its fee payer and its signature is valid.
- It holds at least one instruction of the Hadal program.
- Every instruction calls the Hadal program, the SPL Token or Token-2022 program, the Compute Budget program, the Associated Token Account program or Lighthouse. A System Program instruction is refused.
The API then simulates the exact signed bytes with signatures verified, records the transaction, and broadcasts it. It returns a Transaction with status submitted, with the fields of GET /v1/transactions/:signature.
Sending the same request again returns the transaction's current record, and broadcasts the same bytes once more while its status is still submitted. The same signature with different bytes, another wallet or another lastValidBlockHeight answers IDEMPOTENCY_CONFLICT.
| Error | Stage | Raised when |
|---|---|---|
VALIDATION_ERROR | validation | A field fails its schema, or transactionBase64 is not canonical base64 of a transaction of at most 1232 bytes. |
TRANSACTION_INVALID | wallet | One of the three conditions above does not hold, or a lookup table of the transaction cannot be loaded. |
CHAIN_REFUSED | simulation | A program refused the transaction in simulation. programError names the program and its error. Nothing was broadcast. |
SIMULATION_FAILED | simulation | The simulation failed and no program error could be read from its logs. Answered with HTTP status 400. Nothing was broadcast. |
IDEMPOTENCY_CONFLICT | send | The signature is already recorded with other bytes, wallet or lifetime. |
PROGRAM_UNAVAILABLE | build | GET /health says waiting. |
Also UNSUPPORTED_MEDIA_TYPE, PAYLOAD_TOO_LARGE and RATE_LIMITED, as in Write limits.
GET /v1/transactions/:signature
GET /v1/transactions/:signature:signature is a Signature. Each request reads the signature's status from the chain until the transaction is finalized, failed or expired. It never broadcasts. Returns one Transaction:
| Field | Type | Meaning |
|---|---|---|
signature | Signature | The transaction. |
status | string | submitted, confirmed, finalized, failed or expired. Below. |
submittedAt | Timestamp | When the API recorded it. |
updatedAt | Timestamp | When its status last changed. |
lastValidBlockHeight | integer | As submitted. |
computationId | EntityId | null | The computation the transaction queued, set once the API has indexed the transaction. Follow it with GET /v1/computations/:id. null when it queued none. |
error | ApiError | null | The error envelope when status is failed (CHAIN_REFUSED) or expired (TRANSACTION_EXPIRED). null otherwise. |
| Status | Meaning |
|---|---|
submitted | Broadcast, and the chain has no status for it yet. |
confirmed | Confirmed on chain. |
finalized | Finalized on chain. |
failed | It landed and a program refused it. error.error.programError names the program and its error. |
expired | The block height passed lastValidBlockHeight, the blockhash is no longer valid, and the chain has no record of the signature. It can no longer land. Sign a new transaction. |
Errors: NOT_FOUND, retryable, when the API has no transaction with this signature. NOT_FOUND, not retryable, for a signature that reached the chain without passing through POST /v1/transactions: the API holds no lastValidBlockHeight for it. PROGRAM_UNAVAILABLE.
GET /v1/computations/:id
GET /v1/computations/:id:id is the address of the computation account, from a transaction's computationId or from the computation of an order, deal, transfer or share. It can also be the address of an order, a deal, a balance or a market: the answer is then the latest computation queued for that account. Returns one Computation:
| Field | Type | Meaning |
|---|---|---|
id | EntityId | The computation: the address of its account. |
market | MarketId | The market it runs in. |
owner | Address | The wallet whose balance it acts on. For an order's processing, the order's owner. For a deal's settlement, the maker. |
status | string | queued, done, failed or expired. Below. |
queue | integer | null | null. An order's place in its market's queue is the order's queue field. |
attempt | integer | Which attempt at the action on its account this is, counted from 1. |
queuedAt | Timestamp | The block time of the transaction that queued it. |
updatedAt | Timestamp | When its status last changed. |
signature | Signature | null | The transaction that queued it. |
error | ApiError | null | The error envelope when status is failed: CHAIN_REFUSED with the programError. null otherwise. |
retryOf | EntityId | null | The latest expired computation on the same account, which this one follows. null when there is none. |
| Status | Meaning |
|---|---|
queued | Queued on the cluster. It keeps this status until its result lands or it is released: the chain shows no step in between. |
computing | In the contract's list of values. The API does not report it. |
done | The callback landed and the result is on chain. Read the record it belongs to: the order, deal, transfer, share or balance. |
failed | The callback transaction failed. error.error.programError names the refusal. |
expired | The cluster did not finish it in time and it was released: the deposit was refunded, or the account was freed. A later computation on the same account carries this id in its retryOf. |
The lifecycle is told in Arcium, and expiry and release in When a computation does not finish.
Errors: NOT_FOUND when the API has not indexed a computation for this id, PROGRAM_UNAVAILABLE.
Solana RPC
POST /rpc
POST /rpc
Content-Type: application/jsonA relay to the cluster's Solana RPC for reads and simulation, so a client needs no RPC endpoint of its own. Its full URL is the rpcUrl of GET /v1/markets/:market/config, and a web3.js Connection takes it as its endpoint. The body is one JSON-RPC 2.0 request with an id, a method and params as an array. A batch is refused.
The methods relayed: getAccountInfo, getMultipleAccounts, getBalance, getTokenAccountBalance, getSlot, getBlockHeight, getLatestBlockhash, isBlockhashValid, getFeeForMessage, getMinimumBalanceForRentExemption, getSignatureStatuses, getTransaction, getSignaturesForAddress, getGenesisHash, getVersion, simulateTransaction.
sendTransaction is not relayed. Send a signed transaction through POST /v1/transactions.
The answer is the RPC's own JSON-RPC response. A refusal by the relay is a JSON-RPC error, not the error envelope of the other routes:
| error.code | HTTP | Meaning |
|---|---|---|
-32700 | 400 | The body is not JSON. |
-32600 | 400 or 413 | Not one JSON-RPC 2.0 request with an id, a method and array params, or a body larger than 65536 bytes. |
-32601 | 400 | The method is not relayed. |
-32005 | 429 | More than 600 calls from one client within a minute, or the API is at its own RPC rate. Retry after the Retry-After header. |
-32004 | 200 | GET /health says waiting. |
-32603 | 502 | The cluster RPC did not answer. |
Error codes
Every code in the contract's error table, with its HTTP status.
| Code | Status | Raised when |
|---|---|---|
VALIDATION_ERROR | 400 | A path parameter, query parameter or body field fails its schema, a query parameter the route does not define is present, the JSON body does not parse, or the transaction sent to POST /v1/transactions is not canonical base64 of a Solana transaction of at most 1232 bytes. fieldErrors names each field. Not retryable: correct the request. |
TRANSACTION_INVALID | 400 | POST /v1/transactions refused the signed transaction before simulating it: the wallet is not its fee payer, the fee payer's signature is missing or invalid, it holds no Hadal instruction, it calls a program the relay does not accept, or one of its lookup tables cannot be loaded. Not retryable: build and sign the transaction again. |
UNAUTHORIZED | 401 | In the contract's table. No route raises it: the API has no sign-in. |
ORIGIN_NOT_ALLOWED | 403 | The request carries an Origin header the API does not accept. Not retryable. |
DEAL_NOT_COUNTERPARTY | 403 | In the contract's table. No route raises it: a deal read reports this case in the deal's access field, and the program refuses the answer with NotCounterparty. |
NOT_FOUND | 404 | The API has not indexed a market, order, deal, transfer, transaction or computation with this id: retryable, since a new record appears once its transaction is indexed. Also a signature that was not submitted through POST /v1/transactions, and a path that is not a route: not retryable. |
BALANCE_NOT_FOUND | 404 | In the contract's table. No route raises it: a wallet without a balance in a market gets an empty list. |
PROGRAM_UNAVAILABLE | 409 | The API has not found the Hadal program on chain, so GET /health says waiting. Raised by every read of one record, by the market config and by both transaction routes. Retryable. |
CONFIGURATION_REQUIRED | 409 | GET /v1/markets/:market/config cannot answer because the protocol's share of the sweep fee or the lookup table is not set. Not retryable. |
IDEMPOTENCY_CONFLICT | 409 | A transaction with this signature is already recorded with different signed bytes, another wallet or another lastValidBlockHeight. Not retryable: resend the original request. |
TRANSACTION_EXPIRED | 409 | Carried in a transaction's error when its status is expired: the block height passed lastValidBlockHeight and the chain has no record of the signature. Retryable: sign a new transaction. |
DEAL_EXPIRED | 409 | In the contract's table. No route raises it: a deal read reports status, and the program refuses a late answer with DealExpired. |
DEAL_CANCELLED | 409 | In the contract's table. No route raises it: a deal read reports status cancelled. |
DEAL_OUT_OF_ATTEMPTS | 409 | In the contract's table. No route raises it: a deal read reports attempts and attemptsUsed, and the program refuses the answer with OutOfAttempts. |
COMPUTATION_EXPIRED | 409 | In the contract's table. No route raises it: an expired computation is reported by its status. |
PAYLOAD_TOO_LARGE | 413 | The request body is larger than 65536 bytes. Not retryable. |
UNSUPPORTED_MEDIA_TYPE | 415 | POST /v1/transactions was sent without Content-Type: application/json. Not retryable: set the header. |
SIMULATION_FAILED | 422 | The simulation of the signed transaction failed and no program error could be read from its logs. POST /v1/transactions answers it with HTTP status 400. Retryable. |
CHAIN_REFUSED | 422 | A program refused the transaction, in simulation or on chain. programError carries the program's address, the error's name and its number. Returned by POST /v1/transactions when the simulation is refused, and carried in the error of a failed transaction and a failed computation, where retryable is false. The program's errors are in the program reference. |
COMPUTATION_FAILED | 422 | In the contract's table. No route raises it: a failed computation is reported by its status, with CHAIN_REFUSED in its error. |
RATE_LIMITED | 429 | More than 60 POST requests from one client within a minute. Retryable after retryAfterSeconds, which the Retry-After header repeats. |
INTERNAL_ERROR | 500 | The API could not complete the request. Retryable. Quote the X-Request-Id response header when reporting it. |
UPSTREAM_UNAVAILABLE | 502 | In the contract's table for a chain that cannot be read. The contract's client also reports it for a 5xx response that carries no error envelope. Retryable. |