Agents: metered settlement over x402
A creditor serves while the line is serviceable, records the charge on-chain, and answers a cut-off line with a 402.
Metered settlement over x402
A creditor can front its metered resource with a real HTTP endpoint that follows the HTTP 402 convention but uses its own scheme, encumbra-lien. The agent sends its lien id in an X-Lien-Id header, and the server reads the lien's live state.
- If the line is serviceable and has headroom, the server serves the response and records the charge on-chain.
- Otherwise it returns HTTP 402 Payment Required with headers telling the agent what to settle.
The agent's loop is: call, and on a 402 check why the line is cut off. If the limit is used up, the agent settles on-chain with repay and retries. Repaying reduces debt and restores headroom. It does not clear frozen or a past-due state. A frozen line needs unfreeze from the owner or creditor, and a past-due line needs a cure such as payInstallment on a lease schedule. When the agent cannot fix the cut-off, it stops.
- Agent callswith its lien id in X-Lien-Id
- Server reads the lienserviceable, with room for the price
- Server servesreturns the response
- Charge is recordedon-chain, against the line
- Agent callssame header
- Server returns 402x-price and x-lien-id headers
- Agent settlesrepay, if the limit is used up and the owner funds it
- Agent retriesa frozen or past-due line needs unfreeze or a cure; else it stops
import { x402Request } from "./x402.ts";
let res = await x402Request(baseUrl, lienId, "q=insight-1");
if (res.status === 402) {
const lien = await encumbra.getLien(lienId);
const pastDue =
lien.dueDate !== 0n && BigInt(await chain.now()) > lien.dueDate;
// Repaying restores headroom only. It does not clear a freeze
// or a past-due state, so settle and retry only when neither applies.
if (!lien.frozen && !pastDue) {
await usd.approve(encumbra.address, lien.debt, ownerWallet);
await encumbra.repay(lienId, lien.debt, ownerWallet);
res = await x402Request(baseUrl, lienId, "q=insight-1");
}
}The 402 response carries:
- the
x-payment-required(encumbra-lien),x-priceandx-lien-idheaders - a JSON body with the
scheme(encumbra-lien), areason(limit reached, or lien not serviceable), and a hint to settle the lien and retry
This follows the HTTP 402 convention but uses its own scheme and the X-Lien-Id header. It is not the x402 v1 accepts[] and X-PAYMENT flow, so a client written for that flow will not work against it. The caller has to send X-Lien-Id and read the encumbra-lien response.