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 notapplication/json.VALIDATION_ERROR, at stagevalidation:enclaveKeyEpochis not an unsigned integer,sealedis not base64 or is outside 64 to 16,384 characters, or the body carries another key.UNKNOWN_ENCLAVE_KEY, HTTP 422 at stageauth, before anything is relayed: no registration ofenclaveKeyEpochis active at the current slot or ended fewer than four slots ago, by itsvalidUntilSlot. ReadGET /v1/configand 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 60POSTrequests to/v1in 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.
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) })
curl -X POST https://api.privium.io/v1/intake \
-H 'Content-Type: application/json' \
-d @intake.json
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.
{
"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. |