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.

agent.ts
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()
Reading the remit
const terms = await remit.terms()      // caps, payees, expiry, mint
const balance = await remit.balance()  // what is left to spend

What 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.

agent.ts
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