For agents
An agent with a remit calls paid APIs with one line. When a server answers 402, the SDK pays from the remit and sends the request again.
The one line
The owner opens a remit for the agent’s key in the app and hands over one environment line. The agent’s code changes in one place: fetch becomes remit.fetch. Proofs are made by remit-engine at REMIT_ENGINE_URL, the hosted engine the API names in its config. The agent’s key travels to it in each call.
import { createRemit } from '@remit/sdk'
// Reads REMIT_AGENT_KEY and REMIT_ENGINE_URL from the environment.
const remit = createRemit()
// A fetch that pays. Same arguments, same Response.
const res = await remit.fetch('https://api.lumen.example/search?q=solana')
const results = await res.json()const terms = await remit.terms() // caps, payees, expiry, mint
const balance = await remit.balance() // what is left to spendWhat happens on a 402
- 1. The server names its price
- The 402 body lists what the payee accepts under the scheme
remit: the mint, the price, the payee’s address, how long it will wait, and a hash of the request the payment must bind. - 2. The SDK proves and pays
- It checks the payment against the remit’s terms, has the proof made, and sends
pay. The price leaves the remit and waits in a hold for the payee. - 3. The request goes again
- The retry carries one header with the payment’s signature. The payee reads the hold, serves, and settles. The agent gets the response.
What the agent key can and cannot do
It can
- Find and read its own remit: the balance and every term.
- Pay a payee on the list, up to the cap per payment and the cap per day, until the expiry.
- Pay transaction fees from the SOL the owner sent it when the remit was opened.
It cannot
- Touch the owner’s private balance or any other remit.
- Change a term, add a payee or extend the expiry.
- Build a payment outside the terms, whatever its code or its prompt says: validators reject it.
How a refused payment comes back
A payment outside the terms is refused before any proof exists. The SDK throws a typed error naming the term, and the remit is unchanged.
import { PayeeNotAllowed, OverPaymentCap } from '@remit/sdk'
try {
await remit.fetch('https://api.quarry.example/jobs')
} catch (e) {
if (e instanceof PayeeNotAllowed) {
// The payee is not on this remit's list. Nothing was sent.
}
if (e instanceof OverPaymentCap) {
// The price is above the cap per payment. Nothing was sent.
}
}OverPaymentCap- over the cap per payment
OverDailyCap- over the cap per day
PayeeNotAllowed- payee not on the list
RemitExpired- remit expired
InsufficientRemit- remit too small
HoldExpired- hold past its deadline
PaymentMismatch- payment does not match the request