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 URLnot set yet. On a local network: http://127.0.0.1:4720.
BodiesJSON in and out. Requests with unknown fields are refused.
AmountsBase units of the mint as a decimal string that fits a u64: "250000" is 0.25 of a 6-decimal mint.
Addresses, signaturesBase58.
Hashes32 bytes as 64 hex characters.
Byte blobsBase64.
TimesPublic routes: ISO 8601 UTC strings. Engine routes: unix seconds.
Request idEvery response carries X-Request-Id.
SchemaGET /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:

JSON
{ "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.

FieldTypeMeaning
error.codestringA stable code from the table at the end of this page.
error.messagestringA sentence that can be shown to a person.
error.retryablebooleanWhether the same request can succeed later.
error.stagestringWhere it failed: validation, auth, read, build, wallet, simulation, send or confirmation.
error.fieldErrorsobjectOn VALIDATION_ERROR: messages per field name.
error.programErrorobjectOn CHAIN_REFUSED: programId, name and number of the program error.
error.detailsobjectExtra values for the code, such as the term a payment broke.
error.retryAfterSecondsnumberOn RATE_LIMITED: when to try again.
error.requestIdstringThe same id as X-Request-Id.

Service

GET /health

FieldTypeMeaning
statusstringready, or waiting before the program is deployed on this cluster.
clusterstringmainnet, devnet or localnet.
contractVersionstringThe version of the API's contract.
enginestringok, degraded or unavailable.
slotnumber or nullThe slot the engine last saw.
asOftimeWhen this was answered.

GET /v1/config

Everything a client needs to talk to this cluster.

FieldTypeMeaning
clusterstringmainnet, devnet or localnet.
statusstringAs in /health.
programIdAddress or nullThe Remit program on this cluster.
ringsobjectprivacyProgramId, userRegistryProgramId, stateTree, solInterfacePda.
mintsMintInfo[]The mints the app offers: mint, symbol, name, decimals.
feeBpsnumber or nullThe protocol fee in basis points, 0 to 10,000.
feeRecipientstring or nullThe fee recipient's private address.
remitMintAddress or nullThe REMIT mint.
defaultHoldSecondsnumberThe default time a payee has to settle a hold, in seconds. 300 unless the operator sets another.
engineUrlstringThe base URL of the engine routes.
rpcUrlstringThe Solana RPC URL for this cluster.
asOftimeWhen this was answered.

Directory and standing

GET /v1/payees

Registered payees, one page at a time.

QueryTypeMeaning
qstringMatches name, URL, description or address, case-insensitive. Up to 120 characters.
mintAddressOnly payees priced in this mint.
sortstringsettled (default): most settled first. reliability: fewest refunded first, then most settled. recent: latest first settlement first. name: A to Z.
limit, cursorSee Pages.

Each item is a Payee:

FieldTypeMeaning
payeeAddressThe payee's wallet. This is the address a remit's payee list names.
pdaAddressThe payee's record account on chain.
name, url, descriptionstringWhat the payee registered.
priceHintu64 stringThe payee's typical price per call, in base units of mint. A hint: the price of a call is whatever its gate asks.
mintAddressThe mint the payee prices in.
mintSymbol, mintDecimalsstring, number or nullFilled when the mint is one the app offers.
settledCountnumberPayments settled.
refundedCountnumberHolds refunded.
firstSettledAt, lastSettledAttime or nullThe first and the latest settlement.
registeredAt, updatedAttimeWhen 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

QueryTypeMeaning
daysnumberHow many UTC days to return, ending today. 1 to 365, default 30.
FieldTypeMeaning
payeeAddress
daysnumber
totalsobjectsettledCount, refundedCount, firstSettledAt over the payee's whole history.
seriesobject[]One entry per UTC day, oldest first: date (YYYY-MM-DD), settledCount, refundedCount. Days with nothing are present with zeros.
asOftime

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

FieldTypeMeaning
signaturesignature
slot, blockTimenumber, time or null
instructionKindstringinit_config, set_config, register_payee, update_payee, open, pay, settle, refund or revoke.
instructionTagnumberThe instruction's first byte, 0 to 8 in the order above.
statusstringconfirmed or failed.
feePayer, signersAddress, Address[]
owner, agent, payeeAddress or nullWhichever the instruction names.
remitAuthority, holdAuthorityAddress or nullThe program addresses that own the owner's remits and the payee's holds.
programErrorstring or nullThe 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.

QueryTypeMeaning
kindstringOne of the five instruction names.
agentAddressOnly transactions naming this agent key.
payeeAddressOnly transactions naming this payee.
limit, cursorSee 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.

BodyTypeMeaning
holdOpeningbase64The hold's opening, as tx/pay returned it.
payeeAddressThe hold's payee.
deadlineunix secondsThe hold's deadline.
paySignaturesignature, optionalThe 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.

An owner or a payee
{ "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.

An agent
{ "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:

FieldTypeMeaning
transactionbase64A v1 transaction. Signed when the keys were secret, unsigned when they were wallet.
signersAddress[]The keys that must sign it.
signaturesignature, optionalPresent when the engine signed it in full.

Sign it if it needs signing, then send it with POST /v1/engine/tx/send.

Key routes

RouteBody or queryReturns
GET /v1/engine/healthstatus, 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

RouteBodyReturns
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/opensee belowBuilt and remitId
POST /v1/engine/tx/paysee belowBuilt 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-payeethe sameBuilt
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

BodyTypeMeaning
keyswallet keysThe owner.
agentobject{ 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.
mintAddressThe remit's mint.
amountu64 stringWhat the remit holds, taken from the owner's private balance.
perPaymentCapu64 stringGreater than zero.
dailyCapu64 stringGreater than zero.
payeesAddress[] or "any"1 to 32 addresses, or the string "any".
expiresAtunix seconds
agentFeeLamportsu64 stringSOL 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

BodyTypeMeaning
keyssecret keysThe agent.
remitIdsignature, optionalThe remit to pay from. Without it, the agent's newest remit.
payeeAddress
amountu64 stringThe price.
requestHashhex, 32 bytesThe hash of the request being paid for.
deadlineSecondsnumberHow 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

BodyTypeMeaning
keyswallet keysThe payee.
namestring1 to 64 bytes.
urlstringAn http or https URL, up to 200 bytes.
descriptionstring1 to 280 bytes.
priceHintu64 stringBase units of mint.
mintAddress

View routes

Each decrypts what the keys in the request can read.

RouteBodyReturns
POST /v1/engine/view/balances{ keys }balances: { mint, amount } per mint
POST /v1/engine/view/remits{ keys } of an ownerremits: RemitView[]
POST /v1/engine/view/remit{ keys, remitId } of the ownerRemitView
POST /v1/engine/view/agent{ keys } of an agentremits: AgentRemitView[], the agent's live remits, newest first
POST /v1/engine/view/holds{ keys } of a payeeholds: HoldView[] still held, settled: SettlementView[], each with its receipt string, refunded: HoldView[]
POST /v1/engine/view/payment{ keys, paySignature, requestHash } of a payeeHoldView

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

RouteBodyReturns
POST /v1/engine/receipts/disclose{ keys, paySignature }, owner or payeereceipt: 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

FieldTypeMeaning
remitIdsignatureThe open transaction.
owner, agentAddress
statusstringrevoked once revoked, else expired once the expiry has passed, else empty when nothing is left, else open.
termsTermsmint, perPaymentCap, dailyCap, payees (Address[] or "any"), expiresAt.
openedu64 stringWhat the remit was opened with.
remainingu64 stringWhat it holds now.
spentu64 stringEverything paid from it, not counting payments that were refunded.
spentToday, dayu64 string, numberThe spend counted against the daily cap, and the UTC day number it belongs to.
openedAtunix seconds
paymentsPaymentView[]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

FieldTypeMeaning
paySignaturesignature
payeeAddress
amount, mintu64 string, Address
requestHashhex
deadline, paidAtunix seconds
statusstringheld, settled or refunded.
settleSignature, responseHash, fee, settledAtoptionalPresent 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

CodeStatusRaised when
VALIDATION_ERROR400A field is missing, malformed or unknown. fieldErrors names each.
INVALID_KEYS400The wallet seed or the agent secret key is not valid.
ORIGIN_NOT_ALLOWED403A browser called from an origin the API does not serve.
NOT_FOUND404No such route, payee or transaction.
REMIT_NOT_FOUND404These keys can read no remit with that id.
HOLD_NOT_FOUND404The payment signature created no hold these keys can read.
RECEIPT_NOT_FOUND404The receipt's pay transaction does not exist.
NOT_REGISTERED409The wallet has not registered for a private balance.
PROGRAM_UNAVAILABLE409The program is not deployed on this cluster yet.
CONFIGURATION_REQUIRED409The cluster's program id, fee or fee recipient is not set yet.
TRANSACTION_EXPIRED409The transaction's blockhash expired before it landed. Build it again.
PAYLOAD_TOO_LARGE413The body is over the size limit.
UNSUPPORTED_MEDIA_TYPE415The body is not JSON.
INSUFFICIENT_BALANCE422The private balance is smaller than the amount.
OVER_PAYMENT_CAP422The payment is over the remit's cap per payment.
OVER_DAILY_CAP422The payment would take the day's spend over the cap per day.
PAYEE_NOT_ALLOWED422The payee is not on the remit's list.
REMIT_EXPIRED422The remit's expiry has passed.
INSUFFICIENT_REMIT422The remit holds less than the payment.
HOLD_EXPIRED422The hold's deadline has passed, so it can no longer be settled.
PAYMENT_MISMATCH422The hold does not match the expected payee, amount, mint or request hash.
RECEIPT_MISMATCH422The receipt's values do not match the pay transaction's output.
SIMULATION_FAILED422The transaction failed in simulation before it was sent.
CHAIN_REFUSED422A program rejected the transaction. programError names the error: see The program.
RATE_LIMITED429Too many calls. retryAfterSeconds says when to retry.
INTERNAL_ERROR500The request could not be completed. Retryable.
UPSTREAM_UNAVAILABLE502The engine or the RPC node is unavailable. Retryable.

Loading the index