• Reading the docs…
Start trading

API reference

Intake

The one route that carries sealed Intents to the Coprocessor. It takes the key epoch and the ciphertext, nothing else, and answers with the enclave’s sealed replies.

Route#

POST /v1/intake#

Relays a sealed Intent of any kind (trade, cancel, exit, Receipt request, status or registration) to the Coprocessor’s intake. trade, cancel, exit, receipt and openOrders send every Intent through it, and so do Trade, Account and Receipts in the app. The request carries no account, session or cookie: the account is inside the ciphertext, which only the enclave opens (Intent).

The body is IntakeRequest. Returns IntakeAccepted.

Each envelope in envelopes is the enclave’s reply, sealed to the account’s reply key and signed by the enclave’s signing key. Open it with the account’s keys and check the signature against the signing key it was sealed under, activeEnclave or one of previousEnclaves; the SDK calls return them opened, in submission.results, decodeEnvelope opens one taken from the stream, and the plaintext kinds are in the Type reference. An order the enclave refuses is still answered: its envelope holds the order as rejected, with the reason unfunded when the account’s unreserved balance cannot fund it, or below-minimum when its size is under one denomination unit of the base asset. Every envelope also goes out to all stream readers as an encrypted event (Events).

Sending the same sealed bytes again is safe. Intake answers with the same ticket and the same envelopes, and the nonce is consumed once; receivedAt and nextCrossing are the resend’s. This is how Submission.retry resends an Intent kept after INTAKE_UNAVAILABLE.

Errors

  • UNSUPPORTED_MEDIA_TYPE: the body is not application/json.
  • VALIDATION_ERROR, at stage validation: enclaveKeyEpoch is not an unsigned integer, sealed is not base64 or is outside 64 to 16,384 characters, or the body carries another key.
  • UNKNOWN_ENCLAVE_KEY, HTTP 422 at stage auth, before anything is relayed: no registration of enclaveKeyEpoch is active at the current slot or ended fewer than four slots ago, by its validUntilSlot. Read GET /v1/config and seal again to the active key; not retryable.
  • INTAKE_UNAVAILABLE, HTTP 503: the Coprocessor’s intake is unreachable, did not answer within 15 seconds, or could not confirm or keep the Intent. Keep the sealed bytes and send them again; retryable.
  • RATE_LIMITED: more than 60 POST requests to /v1 in a minute from this client.

The enclave’s own refusals arrive at stage send, not retryable, each with its contract code and that code’s HTTP status:

Code HTTP The enclave refused
ESCAPE_ACTIVE 409 Any Intent while the Escape is active, except a status, a Receipt request, or the registration of an account it already holds.
ACCOUNT_REQUIRED 409 An Intent from an account that has not registered. The SDK sends the registration before an account’s first Intent.
NONCE_USED 409 A nonce the account has consumed: at or below its watermark, held by an open order, or accepted with other bytes (Nonces and replay).
ORDER_EXPIRED 409 An Intent past its expiry slot.
ORDER_NOT_CANCELLABLE 409 A cancel that names no open order of the account.
ASSET_NOT_ADMITTED 409 A pair or an asset the enclave does not carry.
UNKNOWN_ENCLAVE_KEY 422 An Intent sealed to a key the enclave no longer holds active. Read GET /v1/config and seal again to the active key.
SIGNATURE_INVALID 422 A signature that does not verify under the account’s auth key, or a registration whose deposit note names another auth key.
INSUFFICIENT_BALANCE 422 An Exit the account’s unreserved balance does not cover.
BAD_LIMIT 422 A trade Intent with a zero size or limit, or one asset on both sides.
RECEIPT_CLAIM_FALSE 422 A Receipt request with an at-least claim whose figure over the span falls short of its threshold. fieldErrors.claims names the claim’s kind (receipt).
NOT_IMPLEMENTED 501 An Escape Intent: the Escape runs through the relay.
VALIDATION_ERROR 400 Any other Intent it cannot take: bytes that open under no registered enclave key, a plaintext that is not a signed Intent of its fixed length, an Exit below one denomination unit of its asset, or a Receipt request it cannot compute, such as one ending at a Crossing not yet committed or in a quote mint it does not carry.

The sample seals a status Intent by hand, the request openOrders makes in one call.

TypeScript
import { addressBytes, b64, encodeSignedExtendedIntent, extendedSigningBytes, hpkeSeal, intentInfo, nextNonce, sign, unb64, type ExtendedIntent } from '@privium/sdk'

const config = await api.config()
const enclave = config.activeEnclave
const key = { programId: addressBytes(config.programId), epoch: BigInt(enclave.keyEpoch), quoteHash: unb64(enclave.quoteHash), hpkePublicKey: unb64(enclave.hpkeKey) }

const intent: ExtendedIntent = { kind: 'status', account: privium.keys.authPublicKey, nonce: nextNonce(), expiry: (1n << 64n) - 1n }
const signed = encodeSignedExtendedIntent(intent, sign(extendedSigningBytes(intent), privium.keys.authSeed))
const sealed = await hpkeSeal(key.hpkePublicKey, signed, intentInfo(key))

const accepted = await api.intake({ enclaveKeyEpoch: enclave.keyEpoch, sealed: b64(sealed) })

intake.json holds a body as the sample builds it, for a test account: the active key’s epoch and the sealed status Intent, 4,144 bytes as 5,528 base64 characters. Its one envelope opens to the account’s status: no open orders, no pending Exit pieces and its nonce watermark.

Response
{
  "accepted": true,
  "ticket": "dNM2WVePIfNfEeBb3LX9rdS5dy0NqKL6oAjlKGz0UYc=",
  "receivedAt": "2026-11-17T04:28:03.000Z",
  "nextCrossing": "49",
  "envelopes": [
    "z73ShJO9qCQPXDcrZw62Eypn/qnxG4cNsSDxa2Py2m02OdLuYGCI7rUdhXIBVUWSjUY761DEWWMnlO1nIyc3TWUsCUKIiv+tJQYy7wUgdFOyl9CymPvTEZH5r6VAvzB8IoYULzu3J4u6QfT0ILH6oPRskj5KHlS7vZlIkHbyDbB3est+TQW2LYdfDRgAhnbY9ymb8ulr24cUN4mf6WHQUyCMTF3Qc3kzyxwQgRwYsak3Itg3c+rKLMJn4Tkt9aEE7t8gWOU="
  ]
}

Types#

IntakeRequest#

A trade Intent seals to 208 bytes, 280 base64 characters; every other kind to 4,144 bytes, 5,528 characters.

Field Type Meaning
enclaveKeyEpoch U64 The key epoch the Intent was sealed to: the active enclave's keyEpoch. A previous key's epoch is still taken for four slots after its validUntilSlot.
sealed string The sealed Intent, base64, 64 to 16,384 characters.

IntakeAccepted#

Field Type Meaning
accepted true Always true.
ticket Hash SHA-256 of the sealed bytes, base64: the same bytes always have the same ticket.
receivedAt Timestamp When intake answered, to the second.
nextCrossing U64 The Crossing the Intent enters.
envelopes Base64[] The enclave's replies, each sealed to the account's reply key and signed by the enclave, base64. The same envelopes go out as encrypted events.