Encumbra
Menu

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.

Line has headroom
  1. Agent callswith its lien id in X-Lien-Id
  2. Server reads the lienserviceable, with room for the price
  3. Server servesreturns the response
  4. Charge is recordedon-chain, against the line
Line is cut off
  1. Agent callssame header
  2. Server returns 402x-price and x-lien-id headers
  3. Agent settlesrepay, if the limit is used up and the owner funds it
  4. 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");
  }
}
Call, settle on 402 when the limit is used up, retry, backed by a credit line.

The 402 response carries:

  • the x-payment-required (encumbra-lien), x-price and x-lien-id headers
  • a JSON body with the scheme (encumbra-lien), a reason (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.

Keep reading

Local proof of concept. The SDK, x402 server, and underwriter run against an in-process EVM or a local chain with no real funds. The contract is unaudited, and nothing here is financial, legal, or investment advice.