Reference
HTTP API
The app and the SDK use the same JSON API under /api. Amounts are strings of USDC atoms. Writes need a signed-in session, sent as the session cookie or as Authorization: Bearer <token>, and every write except a transaction submission carries an Idempotency-Key header: reuse it only to retry the same request.
Sign-in
| Method | Path | Body | Returns |
|---|---|---|---|
POST | /api/auth/challenge | { wallet } | { nonce, message, expiresAt } |
POST | /api/auth/verify | { wallet, nonce, signature } (base64 Ed25519 over message) | { token, wallet, expiresAt } and the session cookie |
GET | /api/auth/session | — | { wallet }, with wallet: null without a session |
POST | /api/auth/logout | {} | { signedOut: true } |
Reading
| Method | Path | Returns |
|---|---|---|
GET | /api/config | the network, program and lender catalog |
GET | /api/errands?state=OPEN&owner=…&agent=… | up to 100 errands, newest first |
GET | /api/errands/{id} | one errand with its bids, NAV snapshots, state changes and the program account's current figures |
GET | /api/agents | agent profiles and their settled records |
GET | /api/account?owner={wallet} | the wallet's Errand account address, whether it exists, its balances, and availableAtoms: the USDC that can move out now |
GET | /api/transactions/{id} | a prepared transaction's status, for its own wallet |
GET | /api/health and /api/health?ready=1 | liveness, and readiness of the database, chain and worker |
Writing an errand
| Method | Path | Body |
|---|---|---|
POST | /api/compiler | { text, ownerAccount } → the policy, targetAtoms, defaults, policyHash, confirmationHash |
POST | /api/errands | { text, ownerAccount, policyHash, confirmationHash } → the draft |
POST | /api/agents | { name, summary } → the agent profile |
POST | /api/account/transactions | { action: "create" }, { action: "fund", amountAtoms } or { action: "withdraw", amountAtoms } → an unsigned transaction for the wallet to sign and send. withdraw moves USDC back to the wallet, up to availableAtoms |
Transactions
Every on-chain action goes through two calls. The server prepares the exact transaction; your wallet signs it; the server submits the signed bytes and follows them until the chain has finalized them.
| Method | Path | Body |
|---|---|---|
POST | /api/errands/{id}/transactions | { action, …arguments } → { id, transaction } (base64, unsigned) |
POST | /api/transactions/{id}/submit | { signedTransaction } (base64) → { status, signature } |
| Action | Who | Arguments |
|---|---|---|
create | owner | — |
bid | agent | summary, sessionKey, expectedOutcomeAtoms, feeBps, bondAtoms |
award | owner | bidId |
deposit | session key or owner | venueIndex, amountAtoms (USDC) |
withdraw | session key or owner | venueIndex, amountAtoms (receipt tokens) |
recall | owner | — |
settle | owner or session key | — |
cancel | owner | — |
release | the bid's agent | bidId |
revoke_role | owner | — |
Deposits close when the term ends. The session key withdraws until the term ends, or until the recall window closes after a recall; the owner withdraws for as long as the errand is running or recalling. After either deadline, Errand's keeper withdraws what is still lent and settles, and its compensation comes from the winning bond.
The signed message must be the prepared one. A wallet may add its own compute budget and, after the errand's instructions, Lighthouse checks on its balances, as Phantom does; any other change is refused with TRANSACTION_CHANGED. The fee payer must be the signed-in wallet. A transaction the network refuses in simulation comes back as TRANSACTION_REJECTED with the reason, and the same action can be prepared again.
Errors
Errors are { "error": { "code", "message" } } with an HTTP status. The message is written for people; the code is stable for programs.