Guides

Charge for an API with gate

Put a route behind a price, verify each payment yourself, and settle it into a private balance.

This guide puts one route of an API behind a price. At the end an agent's paid call gets your response, the price less the protocol fee is in your private balance, and your settled count has gone up by one.

You need a Solana keypair for the server, with a little SOL for transaction fees. It is the payee's key: payments are made out to its address and it signs each settlement.

  1. Install the SDK

    Shell
    npm install @remit/sdk
  2. Register the payee key for a private balance

    Holds are encrypted to the payee, so the key has to be registered before anyone can pay it. Once is enough.

    register.ts
    import { createOwner } from '@remit/sdk'
    
    const payee = createOwner({ keys: process.env.REMIT_PAYEE_KEY! })
    const { signature } = await payee.register()
    console.log(signature)
    .env
    REMIT_PAYEE_KEY=<the payee's secret key, base58>
    REMIT_ENGINE_URL=<the engine's URL>

    The engine's URL is the engineUrl that GET /v1/config returns from the API at not set yet.

  3. Put the route behind a gate

    server.ts
    import { Hono } from 'hono'
    import { gate } from '@remit/sdk'
    
    const app = new Hono()
    const paid = gate({ price: '40000', mint: process.env.MINT!, network: 'solana-mainnet' })
    
    app.get('/quote', paid.hono(), (c) => c.json({ bid: '184.20', ask: '184.25' }))

    price is in base units of mint: '40000' of a 6-decimal mint such as USDC is 0.04. mint is the mint's address. The gate reads the payee key from REMIT_PAYEE_KEY. Express and Next.js take the same gate: see below.

  4. Call it without paying

    Shell
    curl -i https://api.example.com/quote

    The answer is 402 Payment Required with a body that names your price, your address as payTo, the mint, a requestHash for this exact request and deadlineSeconds, the time you give yourself to settle. An agent's SDK reads that body and pays.

  5. Take a paid call

    Any agent whose remit allows your address and your price can now call the route with remit.fetch. For each paid call the gate:

    1. decrypts the hold the payment created and checks that it is for you, in your mint, for at least your price, for this request, with time left before its deadline
    2. runs your handler and sends its response, with the header X-Remit-Receipt
    3. settles the hold with the hash of the response body

    Settlement runs after the response has gone out, so the caller does not wait for it.

Express and Next.js

The gate is the same object in every framework. Only the adapter differs.

Hono
app.get('/quote', paid.hono(), (c) => c.json({ bid: '184.20', ask: '184.25' }))

Watching settlements

Pass two callbacks to see each settlement land or fail:

TypeScript
import { gate } from '@remit/sdk'

const paid = gate({
  price: '40000',
  mint: process.env.MINT!,
  network: 'solana-mainnet',
  onSettled: (result) => console.log('settled', result.paySignature, result.settleSignature),
  onSettleError: (error, payment) => console.error('settle failed', payment.paySignature, error),
})

A hold that is not settled by its deadline returns to the agent's owner and adds one to your refunded count, so a failed settlement is worth retrying while the deadline allows:

TypeScript
import { settle } from '@remit/sdk'

await settle({ paySignature: '<the pay signature>' }, '<the response body you served>', {})

Settle with the same body you served, so the receipt's response hash matches what the caller received.

The deadline

deadlineSeconds is how long each hold waits for you. The default is 300 and the most is 86,400. Set it to cover your slowest response plus the settlement.

TypeScript
import { gate } from '@remit/sdk'

const paid = gate({
  price: '2500000',
  mint: process.env.MINT!,
  network: 'solana-mainnet',
  deadlineSeconds: 1800,
})

A payment whose hold has less than 15 seconds left when it arrives is refused with 402 and a fresh price, before your handler runs. minSettleBufferSeconds changes the 15.

Routes that take a body

The request hash covers the method, the full URL and the body's bytes. Hono and Next.js give the gate the raw bytes. With Express, keep them on req.rawBody:

TypeScript
import express from 'express'

const app = express()
app.use(express.json({
  verify: (req, _res, buf) => {
    (req as unknown as { rawBody?: Uint8Array }).rawBody = buf
  },
}))

What you receive

Earnings sit in the payee's private balance in the mint you priced in. Withdraw them to any public account:

withdraw.ts
import { createOwner } from '@remit/sdk'

const payee = createOwner({ keys: process.env.REMIT_PAYEE_KEY! })

const balances = await payee.balances()
console.log(balances)

await payee.withdraw({
  mint: process.env.MINT!,
  amount: '1000000',
  destination: '<a token account or wallet address>',
})

More than one price

A gate has one price. Make one per route:

TypeScript
import { Hono } from 'hono'
import { gate } from '@remit/sdk'

const app = new Hono()
const common = { mint: process.env.MINT!, network: 'solana-mainnet' }

app.get('/quote', gate({ ...common, price: '40000' }).hono(), (c) => c.json({ ok: true }))
app.get('/depth', gate({ ...common, price: '250000' }).hono(), (c) => c.json({ ok: true }))

Loading the index