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.

  1. Install the SDK

    Shell
    npm install @remit/sdk

    It is an ES module for Node 18 or later.

  2. 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 the engineUrl that GET /v1/config returns from it.

    REMIT_API_URL is 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.

  3. 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.fetch takes what fetch takes. When the server answers 402 with 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.

  4. 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 against terms before 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.

TypeScript
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
  }
}
OverPaymentCapover the cap per payment
OverDailyCapover the cap per day
PayeeNotAllowedpayee not on the list
RemitExpiredremit expired
InsufficientRemitremit too small
HoldExpiredhold past its deadline
PaymentMismatchpayment 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:

TypeScript
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)
}

Loading the index