Hadal
Start trading
  • OverviewStart
  • QuickstartStart
  • What is sealed and what is seenStart
  • Sealed balancesConcepts
  • Sealed ordersConcepts
  • The book and the pool's midConcepts
  • DealsConcepts
  • SoundingsConcepts
Reference

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.

TypeJSONMeaning
TimestampintegerMilliseconds since the Unix epoch, UTC. Every time field, asOf included, has this type.
SlotintegerA Solana slot number.
AddressstringA base58 address of 32 bytes: a wallet, mint, program or account.
SignaturestringA base58 transaction signature of 64 bytes.
MarketIdstringThe address of the market's Market account. A market's id and its address field hold the same value.
EntityIdstringThe 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.
BaseUnitsstringAn unsigned integer written as a decimal string, counted in atoms of a token. Do arithmetic on it with BigInt.
DecimalStringstringA non-negative decimal number written as a string, for display.
RecordIts idMeaning
MarketAddressThe Market account.
OrderAddressThe Order account.
DealAddressThe Deal account. It is the id in a deal's link.
ComputationAddressThe computation account on Arcium.
Transfer, receipt, eventsignature_nThe 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:

NameTypeMeaning
baseUnitsBaseUnitsThe exact amount in atoms of its token.
decimalDecimalStringThe 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:

NameTypeMeaning
quoteUnitsBaseUnitsNumerator of the exact price: quote atoms.
baseUnitsBaseUnitsDenominator: base atoms. For every price the API serves it is 4294967296 (2^32), so quoteUnits is the price as the program holds it.
decimalDecimalStringQuote 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:

NameTypeMeaning
sealedtrueAlways true. Marks the object as ciphertext.
ciphertextsstring[]The ciphertexts, each the base64 of exactly 32 bytes. How many there are depends on the field, below.
noncestringBase64 of exactly 16 bytes.
encryptionKeystringThe x25519 public key of the owner's reading key: base64 of exactly 32 bytes.
FieldCiphertextsDecodes to
Balance.values, Share.values, Receipt.values, Order.state4A ledger: the owner's base, quote and shares, and the receipt of the last action. Read it with the SDK's Sealer.ledger.
Order.terms5The order's sealed input. Read it with Sealer.open.
Deal.terms5The 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.terms4The 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.

ParameterTypeMeaning
limitintegerItems per response, 1 to 100. Default 24.
cursorstringWhere the response starts. Omit it for the start of the list, then pass the page.nextCursor of the previous response unchanged.
FieldTypeMeaning
itemsarrayThe records of this response.
page.nextCursorstring | nullThe cursor of the next response, or null at the end of the list.
page.hasMorebooleanWhether more records follow.
asOfTimestampWhen the response was read.
freshness'live' | 'stale'See Freshness below.
errorApiError | nullSee 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:

FieldTypeMeaning
error.codestringThe stable code to branch on. All codes are in the table at the end of this page.
error.messagestringOne sentence that can be shown to a person.
error.retryablebooleanWhether sending the same request again can succeed.
error.stagestringWhere the flow failed: validation, auth, read, upload, build, wallet, co_sign, simulation, send or confirmation.
error.fieldErrorsobject, optionalOn VALIDATION_ERROR: field path to a list of messages. A message about the request as a whole is under the key form.
error.programErrorobject, optionalOn CHAIN_REFUSED: programId (Address), name and number of the error of the program that refused.
error.retryAfterSecondsinteger, optionalOn 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

RouteReturnsUse
GET /healthService statusWhether the API has found the program on chain, the contract version it speaks and its clock.
GET /openapi.jsonOpenAPI 3.1 documentEvery route, parameter, response schema and error status in machine-readable form.
GET /v1/marketsPage of marketsEvery open market with its address, tokens, last public price and 24-hour volumes.
GET /v1/markets/:marketMarketOne market by its address.
GET /v1/markets/:market/configMarket configThe program, accounts, vaults, token programs, lookup table, cluster, fee rates and RPC URL a client needs to build transactions for a market.
GET /v1/soundingsPage of soundingsSoundings of all markets, newest first, with an optional market filter.
GET /v1/markets/:market/soundingsPage of soundingsOne market's soundings, oldest first.
GET /v1/markets/:market/candlesPage of candlesOpen, high, low, close and volumes per interval, aggregated from the market's soundings, oldest first.
GET /v1/markets/:market/feesPage of fee payoutsThe protocol fees a market has paid out, in both of its tokens, newest first.
GET /v1/poolsPage of marketsThe same markets as GET /v1/markets, read for their pool's volumes and fee estimate.
GET /v1/totalsTotalsVolume and paid protocol fees to date grouped by mint, the sounding count, and HADAL bought and burned.
GET /v1/eventsPage of public eventsThe public events of all wallets, newest first.
GET /v1/events/streamServer-sent eventsPublic events as they are indexed, with ready and resync messages.
GET /v1/wallets/:wallet/balancesPage of sealed balancesThe wallet's sealed ledger in each market, read from the chain.
GET /v1/wallets/:wallet/sharesPage of liquidity sharesThe same sealed ledgers, each with the wallet's latest liquidity computation.
GET /v1/wallets/:wallet/ordersPage of ordersThe wallet's orders with public kind, status and queue position, sealed terms and latest receipt, newest first.
GET /v1/wallets/:wallet/receiptsPage of receiptsEvery sealed ledger the wallet's actions produced, each with its public kind, account and time, newest first.
GET /v1/wallets/:wallet/dealsPage of dealsThe deals the wallet made, is named in or has answered, newest first.
GET /v1/wallets/:wallet/transfersPage of transfersThe wallet's deposits and withdrawals with their status, newest first.
GET /v1/wallets/:wallet/portfolioPortfolioEverything the wallet holds in one response: balances, shares, orders, deals, receipts and transfers, each list whole.
GET /v1/orders/:idOrderOne order by the address of its Order account.
GET /v1/deals/:idDealOne deal by the address of its Deal account, presented for the wallet passed as viewer.
GET /v1/transfers/:idTransferOne deposit or withdrawal by id.
POST /v1/transactionsTransactionChecks, simulates and broadcasts a transaction the wallet has signed, and returns the record to follow.
GET /v1/transactions/:signatureTransactionThe status of a relayed transaction by its signature.
GET /v1/computations/:idComputationOne computation by its account's address, or the latest computation of an order, deal, balance or market.
POST /rpcJSON-RPC responseRelays one read or simulate call to the cluster's Solana RPC. It does not relay sendTransaction.

Service

GET /health

http
GET /health
FieldTypeMeaning
statusstringwaiting or ready. Below.
contractVersionstringThe version of the contract the API speaks.
timeTimestampThe API's clock.
StatusMeaning
readyThe API has found the Hadal program and its Config account on chain. Every route serves.
waitingIt 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

http
GET /openapi.json

Returns 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

http
GET /v1/markets?limit=24

The markets that are open for trading, ordered by address.

QueryTypeMeaning
marketMarketIdOptional. Return only this market.
limitintegerDefault 24, maximum 100.
cursorstringFrom page.nextCursor.

Returns a page whose items are Market objects:

FieldTypeMeaning
idMarketIdThe market.
addressAddressThe Market account. The same value as id.
readybooleanWhether the market is open for trading.
baseTokenThe base token: symbol (string), mint (Address), decimals (integer). symbol holds the mint address when the API knows no symbol for the mint.
quoteTokenThe quote token, same three fields.
pricePriceThe market's last public price. priceSource says where it comes from.
priceSourcestringsounding, account_snapshot or first_liquidity. Below.
priceAtTimestampTime of the last sounding the API holds, or of its last reading of the market when it holds none.
slotSlotSlot of the last sounding, or of the reading.
crossed24hAmountVolume crossed in the book over the last 24 hours, in the quote token.
swept24hAmountVolume swept from the pool over the last 24 hours, in the quote token.
lpFeesLastSoundingEstimateAmount | nullAn 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.
change24hstringPrice 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.
priceSourceMeaning
soundingThe price of the last sounding the API holds.
account_snapshotThe last sounding price stored on the Market account. The API holds no sounding record for it.
first_liquidityThe market has not been sounded: the price its first liquidity was added at.

GET /v1/markets/:market

http
GET /v1/markets/:market

Returns 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

http
GET /v1/markets/:market/config

Returns 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.

FieldTypeMeaning
marketMarketThe market, as in GET /v1/markets.
programIdAddressThe Hadal program.
configAccountAddressThe program's Config account.
marketAccountAddressThe market's account.
baseVaultAddressThe vault that holds the base token.
quoteVaultAddressThe vault that holds the quote token.
baseTokenProgramAddressThe token program of the base mint.
quoteTokenProgramAddressThe token program of the quote mint.
lookupTableAddressThe address lookup table for the market's transactions.
arciumClusterOffsetintegerThe Arcium cluster the program computes on.
rpcUrlstringThe URL of this API's POST /rpc, for a web3.js Connection.
priceScaleBaseUnitsThe scale of every price and limit: 4294967296.
soundingIntervalSlotsintegerSlots between two soundings.
fees.sweepBpsintegerThe sweep fee in basis points.
fees.crossBpsPerSideintegerThe cross fee each side pays, in basis points.
fees.dealBpsPerSideintegerThe deal fee each side pays, in basis points.
fees.protocolShareOfSweepBpsintegerThe protocol's share of the sweep fee, in basis points of that fee, 0 to 10000.
defaultDealAttemptsintegerAttempts each taker gets on a deal when the maker sets no other number.
feeRecipientAddressThe wallet that receives protocol fees.
hadalMintAddress | nullThe 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

http
GET /v1/soundings?market=:market&from=:ms&to=:ms

Soundings of all markets, newest first.

QueryTypeMeaning
marketMarketIdOptional. Only this market.
fromTimestampOptional. Only soundings at or after this time.
toTimestampOptional. Only soundings at or before this time.
limitintegerDefault 24, maximum 100.
cursorstringFrom page.nextCursor.

Returns a page whose items are Sounding objects:

FieldTypeMeaning
marketMarketIdThe market sounded.
slotSlotThe slot of the sounding.
timeTimestampIts time.
pricePriceThe pool's price.
crossedAmountVolume crossed in the book since the previous sounding, in the quote token.
sweptAmountVolume swept from the pool since the previous sounding, in the quote token.
protocolFeeBaseAmountProtocol fee of the period taken in the base token, in base atoms. Exact.
protocolFeeQuoteAmountProtocol fee of the period taken in the quote token, in quote atoms. Exact.
protocolFeeAmountThe same value as protocolFeeQuote. The base part is not converted into it.
lpFeeEstimateAmount | nullAn 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.
signatureSignatureThe 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:

text
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

http
GET /v1/markets/:market/soundings?from=:ms&to=:ms

One 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

http
GET /v1/markets/:market/candles?interval=5m

Candles of one market, oldest first. A candle aggregates the soundings whose time falls in its interval. It holds no individual fill.

QueryTypeMeaning
intervalstringOne of 1m, 5m, 15m, 1h, 1d. Default 5m.
fromTimestampOptional. Only candles that start at or after this time.
toTimestampOptional. Only candles that start at or before this time.
limitintegerDefault 24, maximum 100.
cursorstringFrom page.nextCursor.

Returns a page whose items are Candle objects:

FieldTypeMeaning
marketMarketIdThe market.
intervalstringThe interval asked for.
timeTimestampStart of the interval.
openPricePrice of the first sounding in the interval.
highPriceHighest sounding price in the interval.
lowPriceLowest sounding price in the interval.
closePricePrice of the last sounding in the interval.
crossedAmountSum of the soundings' crossed volume, in the quote token.
sweptAmountSum of the soundings' swept volume, in the quote token.
soundingsintegerHow many soundings the candle aggregates. At least 1.

Errors: NOT_FOUND, PROGRAM_UNAVAILABLE.

GET /v1/markets/:market/fees

http
GET /v1/markets/:market/fees?from=:ms&to=:ms

The 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:

FieldTypeMeaning
marketMarketIdThe market.
timeTimestampWhen the payout was made.
slotSlotIts slot.
baseAmountBase token paid out.
quoteAmountQuote token paid out.
signatureSignatureThe transaction.

Errors: NOT_FOUND, PROGRAM_UNAVAILABLE.

GET /v1/pools

http
GET /v1/pools

Query: 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

http
GET /v1/totals

Takes no query parameters.

FieldTypeMeaning
volumearrayVolume of all soundings the API holds, crossed and swept together, one entry per quote mint: mint (Address) and amount (Amount).
feesarrayProtocol fees paid out to date, one entry per mint, base and quote mints alike: mint (Address) and amount (Amount).
soundingsintegerHow many soundings the API holds.
hadal.mintAddress | nullThe mint of HADAL. null while not set.
hadal.statusstringmint_not_set while hadal.mint is null, active once it is set.
hadal.boughtAmountHADAL bought with protocol fees to date.
hadal.burnedAmountHADAL burned to date.
asOfTimestampWhen the totals were read.
freshness'live' | 'stale'As for a list.
errorApiError | nullAs 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

http
GET /v1/events?market=:market

What the surface shows wallets doing, newest first. Query: market (optional MarketId), limit, cursor. Returns a page whose items are PublicEvent objects:

FieldTypeMeaning
idEntityIdThe event.
kindstringOne of the six kinds below.
timeTimestampThe block time of its transaction.
walletAddressThe wallet that acted.
marketMarketIdThe market it acted in.
signatureSignatureThe transaction.
amountAmountOnly on deposit and withdraw: the amount.
tokenstringOnly on deposit and withdraw: the symbol of the token, as in the market.
paidbooleanOnly on withdraw: true when the tokens left the vault, false when the withdrawal was refused.
KindMeaning
order_placedThe wallet placed a sealed order. Nothing about the order is in the event.
deal_openedThe wallet opened a deal.
deal_doneThe wallet's answer to a deal traded.
no_dealThe wallet's answer to a deal did not trade.
depositThe wallet sent amount of token to the vault. The event appears when the deposit is queued.
withdrawThe 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

http
GET /v1/events/stream?market=:market
Accept: text/event-stream

The 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:

FieldTypeMeaning
idstringThe id of the message, also sent as the SSE id.
timestampTimestampWhen the message was sent.
typestringready, public_event or resync. Also the SSE event name.
dataobjectDepends on type, below.
TypedataMeaning
readystatusSent 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_eventPublicEventOne public event, with the fields of GET /v1/events.
resyncreasonEvents 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

http
GET /v1/wallets/:wallet/balances

The 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:

FieldTypeMeaning
marketMarketIdThe market.
ownerAddressThe wallet.
valuesSealedThe sealed ledger, four ciphertexts: base, quote and shares held, and the receipt of the last action.
layoutstringledger-v1: values is a ledger.
freshbooleantrue until the first computation writes the ledger. A fresh balance holds nothing.
updatedAtTimestampWhen the API last saw the balance change.

See Sealed balances.

GET /v1/wallets/:wallet/shares

http
GET /v1/wallets/:wallet/shares

A 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

FieldTypeMeaning
computationComputation | nullThe 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

http
GET /v1/wallets/:wallet/orders

Returns a page of Order objects, latest placed first, with the fields of GET /v1/orders/:id.

GET /v1/wallets/:wallet/receipts

http
GET /v1/wallets/:wallet/receipts

The 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:

FieldTypeMeaning
idEntityIdThe receipt.
ownerAddressThe wallet it is encrypted to.
marketMarketIdThe market.
kindstringThe action: order, deal, deposit, withdraw, liquidity, collect or cancel. Below.
accountAddressThe account acted on: orderId when it is set, otherwise dealId, otherwise balanceId.
orderIdEntityId | nullThe order. Set when the action was on an order.
dealIdEntityId | nullThe deal. Set when the action was on a deal.
transferIdEntityId | nullThe transfer. Set when the action finished a deposit or a withdrawal.
balanceIdAddressThe wallet's Balance account in the market.
timeTimestampThe block time of the transaction that emitted the ledger.
slotSlotIts slot.
signatureSignatureThat transaction.
valuesSealedThe sealed ledger, exactly four ciphertexts and their nonce: the balance after the action and the action's receipt.
layoutstringledger-v1: values is a ledger.
KindId setThe ledger was emitted when
orderorderIdThe order was processed.
collectorderIdProceeds of a resting order were collected.
cancelorderId or dealIdWith 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.
dealdealIdFor the maker: the deal's opening landed. For a taker: the taker's answer was computed, whether it traded or not.
deposittransferIdA deposit landed or was refunded.
withdrawtransferIdA withdrawal was paid or refused.
liquiditynoneLiquidity 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

http
GET /v1/wallets/:wallet/deals

The 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

http
GET /v1/wallets/:wallet/transfers

Returns a page of Transfer objects, newest first, with the fields of GET /v1/transfers/:id.

GET /v1/wallets/:wallet/portfolio

http
GET /v1/wallets/:wallet/portfolio

Everything 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.

FieldTypeMeaning
walletAddressThe wallet asked for.
balancesBalance[]Its sealed balances.
sharesShare[]Its liquidity shares.
ordersOrder[]Its orders.
dealsDeal[]Its deals as maker, as counterparty and as answerer.
receiptsReceipt[]Its whole receipt history.
transfersTransfer[]Its deposits and withdrawals.
asOfTimestampWhen the portfolio was read.
freshness'live' | 'stale'As for a list.
errorApiError | nullAs for a list.

Orders

GET /v1/orders/:id

http
GET /v1/orders/:id

:id is the address of the Order account. Returns one Order:

FieldTypeMeaning
idEntityIdThe order: the address of its Order account.
ownerAddressThe wallet that placed it.
marketMarketIdThe market.
kindstringswap or dark. Public.
statusstringpending, resting or closed. Below.
queueinteger | nullThe order's position in the market's queue while it is pending: 1 is the next order processed. null otherwise.
placedAtTimestampWhen it was placed.
expiryTimestamp | nullWhen the order expires. null when it has no expiry.
termsSealedThe sealed input, five ciphertexts.
stateSealedA sealed ledger, four ciphertexts. stateSource says which.
stateSourcestringorder_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.
stateLayoutstringledger-v1: state is a ledger.
receiptReceipt | nullThe order's latest receipt, as in GET /v1/wallets/:wallet/receipts: of kind order, collect or cancel. null until it has one.
returnReasoninteger | nullWhy the order was returned without being processed. Below. null when it was not.
computationComputation | nullThe latest computation queued for the order, as in GET /v1/computations/:id. null when none was queued.
StatusMeaning
pendingThe order is in the market's queue and has not been processed. queue holds its position.
restingA dark order was processed and size of it rests in the sealed book.
closedThe 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.
returnReasonMeaning
0The book was full: a dark order found no free slot.
1The owner cancelled the order while it was pending.
2The order reached the head of the queue after its expiry.
3The 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

http
GET /v1/deals/:id?viewer=:wallet

:id is the address of the Deal account, the id a deal's link carries.

QueryTypeMeaning
viewerAddressOptional. The wallet the deal is presented for. It decides access and which sealed fields are present.

Returns one Deal:

FieldTypeMeaning
idEntityIdThe deal: the address of its Deal account.
marketMarketIdThe market.
makerAddressThe wallet that opened it.
takerAddress | nullThe named counterparty. null when anyone holding the link can answer.
sidestringThe maker's side, public: buy when the maker buys the base token and a taker sells it, sell when the maker sells it.
statusstringopening, open, done, cancelled, expired or void. Below.
attemptsintegerAttempts each taker gets.
attemptsUsedintegerAttempts the viewer has used. 0 without a viewer.
expiryTimestampWhen the deal stops accepting answers.
createdAtTimestampWhen it was opened.
viewerAddress | nullThe viewer passed, or null.
accessstringWhat the viewer is to the deal. Below.
termsSealed | nullThe maker's sealed input, five ciphertexts. Present only when access is maker.
statenullAlways null. The deal's escrow is sealed to the cluster alone and no wallet key reads it.
answerobject | nullThe viewer's last answer. null when the viewer has no computed answer.
answer.outcomestringdone when the answer traded, no_deal when it did not.
answer.termsSealed | nullThe viewer's own sealed input, four ciphertexts.
answer.receiptReceipt | nullThe receipt of that answer, of kind deal, as in GET /v1/wallets/:wallet/receipts.
receiptReceipt | nullThe 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.
computationComputation | nullThe 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.

StatusMeaning
openingThe computation that takes the escrow has not landed.
openThe deal takes answers.
doneIts whole size traded.
cancelledThe maker cancelled it and it is settled.
expiredIt passed its expiry and it is settled.
voidThe escrow was not taken. Nothing moved.
AccessMeaning
makerThe viewer opened the deal.
linkThe deal names no counterparty: anyone holding its link can answer.
counterpartyThe viewer is the named counterparty.
not_counterpartyThe 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

http
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:

FieldTypeMeaning
idEntityIdThe transfer.
kindstringdeposit or withdraw.
statusstringDepends on kind. Below.
ownerAddressThe wallet.
marketMarketIdThe market whose vault the tokens enter or leave.
tokenstringThe symbol of the token, as in the market.
amountAmountThe amount. Deposits and withdrawals are public.
timeTimestampThe block time of the transaction that queued it.
signatureSignature | nullThe transaction that finished the transfer, or the one that queued it while it is pending.
computationComputation | nullThe computation that applies it to the sealed balance, as in GET /v1/computations/:id.
errorApiError | nullnull. A refused withdrawal is told by status, and ok is false in its receipt.
KindStatusMeaning
depositpendingThe tokens are in the vault and the computation that adds them to the sealed balance has not landed.
depositlandedThe amount is in the sealed balance.
depositrefundedThe computation did not finish and the tokens went back to the wallet.
withdrawpendingThe computation that checks the sealed balance has not landed.
withdrawpaidThe tokens moved from the vault to the wallet.
withdrawrefusedThe 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

http
POST /v1/transactions
Content-Type: application/json

Relays a transaction the wallet has already signed. The API adds no signature and changes no byte. The body:

FieldTypeMeaning
walletAddressThe wallet that signed. It must be the fee payer of the transaction.
transactionBase64stringThe whole signed versioned transaction as canonical base64: at most 1232 bytes, 1644 characters.
lastValidBlockHeightintegerThe 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.

ErrorStageRaised when
VALIDATION_ERRORvalidationA field fails its schema, or transactionBase64 is not canonical base64 of a transaction of at most 1232 bytes.
TRANSACTION_INVALIDwalletOne of the three conditions above does not hold, or a lookup table of the transaction cannot be loaded.
CHAIN_REFUSEDsimulationA program refused the transaction in simulation. programError names the program and its error. Nothing was broadcast.
SIMULATION_FAILEDsimulationThe simulation failed and no program error could be read from its logs. Answered with HTTP status 400. Nothing was broadcast.
IDEMPOTENCY_CONFLICTsendThe signature is already recorded with other bytes, wallet or lifetime.
PROGRAM_UNAVAILABLEbuildGET /health says waiting.

Also UNSUPPORTED_MEDIA_TYPE, PAYLOAD_TOO_LARGE and RATE_LIMITED, as in Write limits.

GET /v1/transactions/:signature

http
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:

FieldTypeMeaning
signatureSignatureThe transaction.
statusstringsubmitted, confirmed, finalized, failed or expired. Below.
submittedAtTimestampWhen the API recorded it.
updatedAtTimestampWhen its status last changed.
lastValidBlockHeightintegerAs submitted.
computationIdEntityId | nullThe computation the transaction queued, set once the API has indexed the transaction. Follow it with GET /v1/computations/:id. null when it queued none.
errorApiError | nullThe error envelope when status is failed (CHAIN_REFUSED) or expired (TRANSACTION_EXPIRED). null otherwise.
StatusMeaning
submittedBroadcast, and the chain has no status for it yet.
confirmedConfirmed on chain.
finalizedFinalized on chain.
failedIt landed and a program refused it. error.error.programError names the program and its error.
expiredThe 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

http
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:

FieldTypeMeaning
idEntityIdThe computation: the address of its account.
marketMarketIdThe market it runs in.
ownerAddressThe wallet whose balance it acts on. For an order's processing, the order's owner. For a deal's settlement, the maker.
statusstringqueued, done, failed or expired. Below.
queueinteger | nullnull. An order's place in its market's queue is the order's queue field.
attemptintegerWhich attempt at the action on its account this is, counted from 1.
queuedAtTimestampThe block time of the transaction that queued it.
updatedAtTimestampWhen its status last changed.
signatureSignature | nullThe transaction that queued it.
errorApiError | nullThe error envelope when status is failed: CHAIN_REFUSED with the programError. null otherwise.
retryOfEntityId | nullThe latest expired computation on the same account, which this one follows. null when there is none.
StatusMeaning
queuedQueued on the cluster. It keeps this status until its result lands or it is released: the chain shows no step in between.
computingIn the contract's list of values. The API does not report it.
doneThe callback landed and the result is on chain. Read the record it belongs to: the order, deal, transfer, share or balance.
failedThe callback transaction failed. error.error.programError names the refusal.
expiredThe 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

http
POST /rpc
Content-Type: application/json

A 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.codeHTTPMeaning
-32700400The body is not JSON.
-32600400 or 413Not one JSON-RPC 2.0 request with an id, a method and array params, or a body larger than 65536 bytes.
-32601400The method is not relayed.
-32005429More than 600 calls from one client within a minute, or the API is at its own RPC rate. Retry after the Retry-After header.
-32004200GET /health says waiting.
-32603502The cluster RPC did not answer.

Error codes

Every code in the contract's error table, with its HTTP status.

CodeStatusRaised when
VALIDATION_ERROR400A 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_INVALID400POST /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.
UNAUTHORIZED401In the contract's table. No route raises it: the API has no sign-in.
ORIGIN_NOT_ALLOWED403The request carries an Origin header the API does not accept. Not retryable.
DEAL_NOT_COUNTERPARTY403In 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_FOUND404The 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_FOUND404In the contract's table. No route raises it: a wallet without a balance in a market gets an empty list.
PROGRAM_UNAVAILABLE409The 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_REQUIRED409GET /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_CONFLICT409A transaction with this signature is already recorded with different signed bytes, another wallet or another lastValidBlockHeight. Not retryable: resend the original request.
TRANSACTION_EXPIRED409Carried 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_EXPIRED409In the contract's table. No route raises it: a deal read reports status, and the program refuses a late answer with DealExpired.
DEAL_CANCELLED409In the contract's table. No route raises it: a deal read reports status cancelled.
DEAL_OUT_OF_ATTEMPTS409In the contract's table. No route raises it: a deal read reports attempts and attemptsUsed, and the program refuses the answer with OutOfAttempts.
COMPUTATION_EXPIRED409In the contract's table. No route raises it: an expired computation is reported by its status.
PAYLOAD_TOO_LARGE413The request body is larger than 65536 bytes. Not retryable.
UNSUPPORTED_MEDIA_TYPE415POST /v1/transactions was sent without Content-Type: application/json. Not retryable: set the header.
SIMULATION_FAILED422The 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_REFUSED422A 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_FAILED422In the contract's table. No route raises it: a failed computation is reported by its status, with CHAIN_REFUSED in its error.
RATE_LIMITED429More than 60 POST requests from one client within a minute. Retryable after retryAfterSeconds, which the Retry-After header repeats.
INTERNAL_ERROR500The API could not complete the request. Retryable. Quote the X-Request-Id response header when reporting it.
UPSTREAM_UNAVAILABLE502In 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.