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.
Install the SDK
Shell npm install @remit/sdkRegister 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
engineUrlthatGET /v1/configreturns from the API atnot set yet.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' }))priceis in base units ofmint:'40000'of a 6-decimal mint such as USDC is 0.04.mintis the mint's address. The gate reads the payee key fromREMIT_PAYEE_KEY. Express and Next.js take the same gate: see below.Call it without paying
Shell curl -i https://api.example.com/quoteThe answer is
402 Payment Requiredwith a body that names your price, your address aspayTo, the mint, arequestHashfor this exact request anddeadlineSeconds, the time you give yourself to settle. An agent's SDK reads that body and pays.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:- 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
- runs your handler and sends its response, with the header
X-Remit-Receipt - 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.
app.get('/quote', paid.hono(), (c) => c.json({ bid: '184.20', ask: '184.25' }))app.get('/quote', paid.express(), (req, res) => {
res.json({ bid: '184.20', ask: '184.25' })
})export const GET = paid.next(async () => Response.json({ bid: '184.20', ask: '184.25' }))Watching settlements
Pass two callbacks to see each settlement land or fail:
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:
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.
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:
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:
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:
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 }))