Reference
The API
Every endpoint of the Remit API: the directory and standing, public transaction facts, and the engine routes that build, prove and read.
The API has two halves. The public routes serve what is on chain for anyone to read: the directory, standing, and the public facts of Remit transactions. The engine routes, under /v1/engine, build and prove transactions and read private state with keys the caller sends in the request.
The SDK and the app call these routes for you. Use them directly when you build your own client.
Conventions
| Base URL | not set yet. On a local network: http://127.0.0.1:4720. |
| Bodies | JSON in and out. Requests with unknown fields are refused. |
| Amounts | Base units of the mint as a decimal string that fits a u64: "250000" is 0.25 of a 6-decimal mint. |
| Addresses, signatures | Base58. |
| Hashes | 32 bytes as 64 hex characters. |
| Byte blobs | Base64. |
| Times | Public routes: ISO 8601 UTC strings. Engine routes: unix seconds. |
| Request id | Every response carries X-Request-Id. |
| Schema | GET /openapi.json returns the OpenAPI 3.1 document of every route. |
Pages
List routes take limit (1 to 100, default 24) and cursor, and return:
{ "items": [], "page": { "nextCursor": "24", "hasMore": true }, "asOf": "2026-11-22T10:00:00.000Z" }Pass page.nextCursor as cursor to get the next page. It is null on the last one.
Errors
Every failed call answers with one envelope. Branch on error.code.
| Field | Type | Meaning |
|---|---|---|
error.code | string | A stable code from the table at the end of this page. |
error.message | string | A sentence that can be shown to a person. |
error.retryable | boolean | Whether the same request can succeed later. |
error.stage | string | Where it failed: validation, auth, read, build, wallet, simulation, send or confirmation. |
error.fieldErrors | object | On VALIDATION_ERROR: messages per field name. |
error.programError | object | On CHAIN_REFUSED: programId, name and number of the program error. |
error.details | object | Extra values for the code, such as the term a payment broke. |
error.retryAfterSeconds | number | On RATE_LIMITED: when to try again. |
error.requestId | string | The same id as X-Request-Id. |
Service
GET /health
| Field | Type | Meaning |
|---|---|---|
status | string | ready, or waiting before the program is deployed on this cluster. |
cluster | string | mainnet, devnet or localnet. |
contractVersion | string | The version of the API's contract. |
engine | string | ok, degraded or unavailable. |
slot | number or null | The slot the engine last saw. |
asOf | time | When this was answered. |
GET /v1/config
Everything a client needs to talk to this cluster.
| Field | Type | Meaning |
|---|---|---|
cluster | string | mainnet, devnet or localnet. |
status | string | As in /health. |
programId | Address or null | The Remit program on this cluster. |
rings | object | privacyProgramId, userRegistryProgramId, stateTree, solInterfacePda. |
mints | MintInfo[] | The mints the app offers: mint, symbol, name, decimals. |
feeBps | number or null | The protocol fee in basis points, 0 to 10,000. |
feeRecipient | string or null | The fee recipient's private address. |
remitMint | Address or null | The REMIT mint. |
defaultHoldSeconds | number | The default time a payee has to settle a hold, in seconds. 300 unless the operator sets another. |
engineUrl | string | The base URL of the engine routes. |
rpcUrl | string | The Solana RPC URL for this cluster. |
asOf | time | When this was answered. |
Directory and standing
GET /v1/payees
Registered payees, one page at a time.
| Query | Type | Meaning |
|---|---|---|
q | string | Matches name, URL, description or address, case-insensitive. Up to 120 characters. |
mint | Address | Only payees priced in this mint. |
sort | string | settled (default): most settled first. reliability: fewest refunded first, then most settled. recent: latest first settlement first. name: A to Z. |
limit, cursor | See Pages. |
Each item is a Payee:
| Field | Type | Meaning |
|---|---|---|
payee | Address | The payee's wallet. This is the address a remit's payee list names. |
pda | Address | The payee's record account on chain. |
name, url, description | string | What the payee registered. |
priceHint | u64 string | The payee's typical price per call, in base units of mint. A hint: the price of a call is whatever its gate asks. |
mint | Address | The mint the payee prices in. |
mintSymbol, mintDecimals | string, number or null | Filled when the mint is one the app offers. |
settledCount | number | Payments settled. |
refundedCount | number | Holds refunded. |
firstSettledAt, lastSettledAt | time or null | The first and the latest settlement. |
registeredAt, updatedAt | time | When the record was created and last edited. |
GET /v1/payees/:payee
One Payee with asOf. NOT_FOUND when the address has no record.
GET /v1/payees/:payee/standing
| Query | Type | Meaning |
|---|---|---|
days | number | How many UTC days to return, ending today. 1 to 365, default 30. |
| Field | Type | Meaning |
|---|---|---|
payee | Address | |
days | number | |
totals | object | settledCount, refundedCount, firstSettledAt over the payee's whole history. |
series | object[] | One entry per UTC day, oldest first: date (YYYY-MM-DD), settledCount, refundedCount. Days with nothing are present with zeros. |
asOf | time |
Public transaction facts
These routes hold what any explorer shows of a Remit transaction, already decoded. They never hold an amount, a term or a request.
GET /v1/transactions/:signature
| Field | Type | Meaning |
|---|---|---|
signature | signature | |
slot, blockTime | number, time or null | |
instructionKind | string | init_config, set_config, register_payee, update_payee, open, pay, settle, refund or revoke. |
instructionTag | number | The instruction's first byte, 0 to 8 in the order above. |
status | string | confirmed or failed. |
feePayer, signers | Address, Address[] | |
owner, agent, payee | Address or null | Whichever the instruction names. |
remitAuthority, holdAuthority | Address or null | The program addresses that own the owner's remits and the payee's holds. |
programError | string or null | The program error's name when the transaction failed. |
NOT_FOUND when the signature is not a Remit transaction the indexer has seen.
GET /v1/owners/:owner/activity
The owner's open, pay, settle, refund and revoke transactions, newest first. This is the list of signatures a statement is decrypted from.
| Query | Type | Meaning |
|---|---|---|
kind | string | One of the five instruction names. |
agent | Address | Only transactions naming this agent key. |
payee | Address | Only transactions naming this payee. |
limit, cursor | See Pages. |
Each item: signature, kind, slot, blockTime, status, owner, remitAuthority, agent, payee.
GET /v1/payees/:payee/activity
The payee's pay, settle and refund transactions, newest first. kind filters to one of the three. Each item: signature, kind, slot, blockTime, status, payee, holdAuthority, owner, agent.
Handing a hold to the keeper
POST /v1/holds
Gives Remit's keeper the opening of a hold, so that it sends refund if the deadline passes unsettled.
| Body | Type | Meaning |
|---|---|---|
holdOpening | base64 | The hold's opening, as tx/pay returned it. |
payee | Address | The hold's payee. |
deadline | unix seconds | The hold's deadline. |
paySignature | signature, optional | The pay transaction. Sending the same signature again replaces the stored opening. |
Answers 201 with id, payee, deadline and storedAt. Limited to 60 calls a minute per client; past that it answers RATE_LIMITED with retryAfterSeconds.
Engine routes
Every engine route is under /v1/engine. The engine builds each transaction with its proof and decrypts private state. It keeps nothing between calls: keys arrive in the request that needs them and are neither stored nor logged.
Keys
A call that needs keys takes a keys object, one of two kinds.
{ "kind": "wallet", "wallet": "<address>", "seed": "<base64, 64 bytes>" }seed is the wallet's signature over the key-derivation message from GET /v1/engine/keys/derivation-message. Transactions come back unsigned, with the wallet as fee payer, for the wallet to sign.
{ "kind": "secret", "secretKey": "<base58, 64 bytes>" }The engine signs with the agent key and returns the transaction signed.
Built
Every tx route answers with a built transaction:
| Field | Type | Meaning |
|---|---|---|
transaction | base64 | A v1 transaction. Signed when the keys were secret, unsigned when they were wallet. |
signers | Address[] | The keys that must sign it. |
signature | signature, optional | Present when the engine signed it in full. |
Sign it if it needs signing, then send it with POST /v1/engine/tx/send.
Key routes
| Route | Body or query | Returns |
|---|---|---|
GET /v1/engine/health | status, programId, cluster, slot | |
GET /v1/engine/keys/derivation-message | ?wallet=<address> | message: the exact bytes for the wallet to sign, base64 |
POST /v1/engine/keys/address | { keys } | wallet, shieldedAddress, viewingPubkey, ownerHash, registered |
registered says whether the wallet has a private balance others can pay.
Transaction routes
| Route | Body | Returns |
|---|---|---|
POST /v1/engine/tx/register | { keys } | Built |
POST /v1/engine/tx/deposit | { keys, mint, amount } | Built |
POST /v1/engine/tx/withdraw | { keys, mint, amount, destination } | Built |
POST /v1/engine/tx/open | see below | Built and remitId |
POST /v1/engine/tx/pay | see below | Built and holdOpening |
POST /v1/engine/tx/settle | { keys, paySignature, responseHash } | Built |
POST /v1/engine/tx/refund | { keys, hold } | Built |
POST /v1/engine/tx/revoke | { keys, remitId } | Built |
POST /v1/engine/tx/register-payee | { keys, name, url, description, priceHint, mint } | Built |
POST /v1/engine/tx/update-payee | the same | Built |
POST /v1/engine/tx/init-config, set-config | { keys, feeBps, feeRecipient } | Built. For the program's admin. |
POST /v1/engine/tx/send | { transaction } | signature, once the transaction is confirmed |
amount is greater than zero everywhere. destination is the public account a withdrawal pays. In refund, keys is whoever pays the transaction fee and hold is the hold's opening.
open
| Body | Type | Meaning |
|---|---|---|
keys | wallet keys | The owner. |
agent | object | { shieldedAddress }: the agent key's private address, as keys/address returns it. Or { pubkey, viewingPubkey } of a key that has registered for a private balance; NOT_REGISTERED otherwise. |
mint | Address | The remit's mint. |
amount | u64 string | What the remit holds, taken from the owner's private balance. |
perPaymentCap | u64 string | Greater than zero. |
dailyCap | u64 string | Greater than zero. |
payees | Address[] or "any" | 1 to 32 addresses, or the string "any". |
expiresAt | unix seconds | |
agentFeeLamports | u64 string | SOL sent to the agent key for transaction fees, in lamports. May be "0". |
remitId in the answer is the signature the transaction will have. It names the remit from then on.
pay
| Body | Type | Meaning |
|---|---|---|
keys | secret keys | The agent. |
remitId | signature, optional | The remit to pay from. Without it, the agent's newest remit. |
payee | Address | |
amount | u64 string | The price. |
requestHash | hex, 32 bytes | The hash of the request being paid for. |
deadlineSeconds | number | How long the payee has to settle, at most 86,400. |
holdOpening in the answer is the new hold's opening, base64: the value POST /v1/holds takes.
The engine checks the payment against the remit's terms before it proves anything. A payment that breaks a term answers 422 with the code that names the term (OVER_PAYMENT_CAP, OVER_DAILY_CAP, PAYEE_NOT_ALLOWED, REMIT_EXPIRED, INSUFFICIENT_REMIT), and no transaction exists.
register-payee, update-payee
| Body | Type | Meaning |
|---|---|---|
keys | wallet keys | The payee. |
name | string | 1 to 64 bytes. |
url | string | An http or https URL, up to 200 bytes. |
description | string | 1 to 280 bytes. |
priceHint | u64 string | Base units of mint. |
mint | Address |
View routes
Each decrypts what the keys in the request can read.
| Route | Body | Returns |
|---|---|---|
POST /v1/engine/view/balances | { keys } | balances: { mint, amount } per mint |
POST /v1/engine/view/remits | { keys } of an owner | remits: RemitView[] |
POST /v1/engine/view/remit | { keys, remitId } of the owner | RemitView |
POST /v1/engine/view/agent | { keys } of an agent | remits: AgentRemitView[], the agent's live remits, newest first |
POST /v1/engine/view/holds | { keys } of a payee | holds: HoldView[] still held, settled: SettlementView[], each with its receipt string, refunded: HoldView[] |
POST /v1/engine/view/payment | { keys, paySignature, requestHash } of a payee | HoldView |
view/payment is the gate's check. It decrypts the hold the pay transaction created and answers PAYMENT_MISMATCH when the hold is not for this payee or this request hash, HOLD_NOT_FOUND when the transaction created none, and HOLD_EXPIRED when the deadline has passed.
Receipt routes
| Route | Body | Returns |
|---|---|---|
POST /v1/engine/receipts/disclose | { keys, paySignature }, owner or payee | receipt: the string to hand over |
POST /v1/engine/receipts/verify | { receipt } | ReceiptView |
verify takes no keys and answers RECEIPT_NOT_FOUND for a string that is not a receipt. Receipts and disclosure describes what it checks.
Shapes
RemitView
| Field | Type | Meaning |
|---|---|---|
remitId | signature | The open transaction. |
owner, agent | Address | |
status | string | revoked once revoked, else expired once the expiry has passed, else empty when nothing is left, else open. |
terms | Terms | mint, perPaymentCap, dailyCap, payees (Address[] or "any"), expiresAt. |
opened | u64 string | What the remit was opened with. |
remaining | u64 string | What it holds now. |
spent | u64 string | Everything paid from it, not counting payments that were refunded. |
spentToday, day | u64 string, number | The spend counted against the daily cap, and the UTC day number it belongs to. |
openedAt | unix seconds | |
payments | PaymentView[] | The statement, newest first. |
AgentRemitView
What an agent reads of its remit: remitId, owner, terms, opened, remaining, spentToday and day, with the same meanings as in RemitView.
PaymentView
| Field | Type | Meaning |
|---|---|---|
paySignature | signature | |
payee | Address | |
amount, mint | u64 string, Address | |
requestHash | hex | |
deadline, paidAt | unix seconds | |
status | string | held, settled or refunded. |
settleSignature, responseHash, fee, settledAt | optional | Present once settled. fee is what the payee paid. |
HoldView and SettlementView
A HoldView has paySignature, owner, payee, amount, mint, requestHash, deadline, paidAt and status. A SettlementView adds settleSignature, responseHash, fee, net (the amount less the fee) and settledAt.
ReceiptView
paySignature, payee, owner, amount, mint, requestHash, status and paidAt, with settleSignature, responseHash and settledAt once settled.
Error codes
| Code | Status | Raised when |
|---|---|---|
VALIDATION_ERROR | 400 | A field is missing, malformed or unknown. fieldErrors names each. |
INVALID_KEYS | 400 | The wallet seed or the agent secret key is not valid. |
ORIGIN_NOT_ALLOWED | 403 | A browser called from an origin the API does not serve. |
NOT_FOUND | 404 | No such route, payee or transaction. |
REMIT_NOT_FOUND | 404 | These keys can read no remit with that id. |
HOLD_NOT_FOUND | 404 | The payment signature created no hold these keys can read. |
RECEIPT_NOT_FOUND | 404 | The receipt's pay transaction does not exist. |
NOT_REGISTERED | 409 | The wallet has not registered for a private balance. |
PROGRAM_UNAVAILABLE | 409 | The program is not deployed on this cluster yet. |
CONFIGURATION_REQUIRED | 409 | The cluster's program id, fee or fee recipient is not set yet. |
TRANSACTION_EXPIRED | 409 | The transaction's blockhash expired before it landed. Build it again. |
PAYLOAD_TOO_LARGE | 413 | The body is over the size limit. |
UNSUPPORTED_MEDIA_TYPE | 415 | The body is not JSON. |
INSUFFICIENT_BALANCE | 422 | The private balance is smaller than the amount. |
OVER_PAYMENT_CAP | 422 | The payment is over the remit's cap per payment. |
OVER_DAILY_CAP | 422 | The payment would take the day's spend over the cap per day. |
PAYEE_NOT_ALLOWED | 422 | The payee is not on the remit's list. |
REMIT_EXPIRED | 422 | The remit's expiry has passed. |
INSUFFICIENT_REMIT | 422 | The remit holds less than the payment. |
HOLD_EXPIRED | 422 | The hold's deadline has passed, so it can no longer be settled. |
PAYMENT_MISMATCH | 422 | The hold does not match the expected payee, amount, mint or request hash. |
RECEIPT_MISMATCH | 422 | The receipt's values do not match the pay transaction's output. |
SIMULATION_FAILED | 422 | The transaction failed in simulation before it was sent. |
CHAIN_REFUSED | 422 | A program rejected the transaction. programError names the error: see The program. |
RATE_LIMITED | 429 | Too many calls. retryAfterSeconds says when to retry. |
INTERNAL_ERROR | 500 | The request could not be completed. Retryable. |
UPSTREAM_UNAVAILABLE | 502 | The engine or the RPC node is unavailable. Retryable. |