Guides
Give an agent a remit with the SDK
Install the SDK, hand the agent its key, and replace fetch with a fetch that pays from the remit.
This guide takes an agent from a key to a paid call. At the end the agent has the response in its hands, a hold for the price exists on chain, and the payment is in the owner's statement.
You need a remit opened for the agent and the agent's secret key. The owner gets both on Open a remit: Open a remit in the app.
Install the SDK
Shell npm install @remit/sdkIt is an ES module for Node 18 or later.
Give the agent its key and the two URLs
.env REMIT_AGENT_KEY=<the agent's secret key> REMIT_ENGINE_URL=<the engine's URL> REMIT_API_URL=<the API's URL>The app shows the first line when the remit is opened. The API's URL is
not set yet, and the engine's URL is theengineUrlthatGET /v1/configreturns from it.REMIT_API_URLis optional. With it set, each payment's hold is handed to Remit's keeper, which refunds the owner if the payee has not settled by the deadline.Pay for a call
agent.ts import { createRemit } from '@remit/sdk' const remit = createRemit() const response = await remit.fetch('https://api.example.com/quote?pair=SOL-USDC') console.log(response.status, await response.json()) console.log(response.headers.get('x-remit-receipt'))remit.fetchtakes whatfetchtakes. When the server answers402with a Remit price, the SDK pays it from the remit and sends the request again. An API that asks for no payment is called once and costs nothing.The response carries
X-Remit-Receipt: the signature of the payment, which names it in the owner's statement.Read what the remit allows
TypeScript const terms = await remit.terms() const balance = await remit.balance() console.log(terms.perPaymentCap, terms.dailyCap, terms.payees, terms.expiresAt) console.log(balance.remaining, balance.spentToday)Amounts are strings in base units of the remit's mint:
"250000"is 0.25 USDC. An agent can check a price againsttermsbefore it calls.
When a payment is refused
A price outside the remit's terms is never paid. remit.fetch throws before any transaction exists, and the error's class names the term.
import {
createRemit,
OverPaymentCap,
OverDailyCap,
PayeeNotAllowed,
RemitExpired,
InsufficientRemit,
} from '@remit/sdk'
const remit = createRemit()
try {
await remit.fetch('https://api.example.com/jobs')
} catch (error) {
if (error instanceof PayeeNotAllowed) {
console.log('This API is not on the remit’s payee list.')
} else if (error instanceof OverPaymentCap || error instanceof OverDailyCap) {
console.log('The price is over a cap:', error.message)
} else if (error instanceof RemitExpired || error instanceof InsufficientRemit) {
console.log('The remit can pay nothing more:', error.message)
} else {
throw error
}
}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 |
The remit is unchanged after a refusal: nothing was spent and the day's count did not move. To pay that price, the owner opens a remit whose terms allow it.
An agent that reports back to a model passes error.name and error.message on, so the model can say which term stopped it.
What a payment costs the agent
Each payment is one Solana transaction signed by the agent key. Its fee comes out of the SOL the owner sent the key when the remit was opened. The price itself comes out of the remit.
Paying without remit.fetch
To handle the 402 yourself, read the price from the body and pay it with remit.pay:
import { createRemit, type PaymentRequiredBody } from '@remit/sdk'
const remit = createRemit()
const url = 'https://api.example.com/quote'
const first = await fetch(url)
if (first.status === 402) {
const body = (await first.json()) as PaymentRequiredBody
const paid = await remit.pay(body.accepts[0])
const second = await fetch(url, { headers: { 'X-Remit-Payment': paid.signature } })
console.log(second.status)
}