Pay only for what was delivered.

Gage is a verifier for x402 on Solana. The tool's 402 points the payment at a Gage vault instead of the tool. Gage holds the money, lets the tool answer, runs five mechanical checks on the response, then releases the hold to the tool or refunds the agent. Two headers on the agent side, one middleware on the tool side, and every verdict is recomputable by anyone.

Check that the verifier you are talking to is up:

curl /info

Quickstart

Two SDKs, one line each. They live in the repository as @gage/agent and @gage/provider (npm release pending), and everything they do is plain HTTP, documented below, so any language works without them.

Pay for a tool (agent side)

Wrap fetch. When a tool answers 402 with Gage terms, the wrapper signs the payment, attaches what it expects back, retries, and reads the verdict from the response.

import { wrapFetchWithGage } from "@gage/agent";

// signer: any ed25519 key, 64-byte Solana layout (seed || pubkey)
const f = wrapFetchWithGage(fetch, {
  signer: { secretKey },
  maxAmount: "10000",            // refuse any quote above 0.01 USDC (atomic units)
  schema: searchSchema,          // what a valid answer looks like (JSON schema)
  rpcUrl: "https://api.devnet.solana.com",   // only for chain modes
});

const res = await f("https://tool.example/v1/search?q=solana");
const body = await res.json();
// PAYMENT-RESPONSE on `res` carries the verdict: released to the tool, or refunded to you.

# 1. call the tool, get a 402 with Gage terms
GET /v1/search?q=solana
→ 402, header PAYMENT-REQUIRED: base64({ x402Version: 2, accepts: [PaymentRequirements] })
   accepts[0].payTo is the Gage vault, accepts[0].extra.gage.verifier is the verifier URL

# 2. retry with two headers
GET /v1/search?q=solana
PAYMENT-SIGNATURE: base64(PaymentPayload)     # the signed payment to payTo, see Objects
GAGE-EXPECT:       base64(Expectation)        # requestHash, quotedAmount, schema, nonce

# 3. read the answer and the verdict
→ 200, body, header PAYMENT-RESPONSE: base64({ success, holdId, verdict })

Get paid (tool side)

One middleware in front of the paid route. It answers 402 with the vault as payTo, opens the hold when a payment arrives, runs your handler, reports the delivery, and attaches the verdict.

import { gagePaid } from "@gage/provider";

app.use("/v1/search", gagePaid({
  verifier: "",
  providerId: PROVIDER_PUBKEY,   // your identity in the registry
  amount: "10000",               // 0.01 USDC per call
  schema: searchSchema,          // the shape you commit to
}));

app.get("/v1/search", c => c.json({ query: c.req.query("q"), results: [...] }));

# once: read the vault and network you will quote
GET /info

# no PAYMENT-SIGNATURE on the request → answer 402
PAYMENT-REQUIRED: base64({ x402Version: 2, accepts: [{ scheme: "exact", network, asset, amount, payTo: info.payTo,
  maxTimeoutSeconds: 60, resource, extra: { gage: { verifier, providerId, schemaHash } } }] })

# PAYMENT-SIGNATURE + GAGE-EXPECT present → open the hold
POST /settle  { paymentPayload, paymentRequirements, expectation }
→ { success: true, holdId, payer }

# run your handler, then report exactly what you sent
POST /holds/{holdId}/deliver
  { status: 200, contentType: "application/json", body: "<response text>", requestHash, priceCharged: "10000" }
→ { verdict }     # put base64({ success: true, holdId, verdict }) in PAYMENT-RESPONSE

The flow

x402 v2, unchanged, with one thing moved: where the settlement lands. Gage sits between the tool and the agent's money.

1. Quote. The agent calls the tool. The tool answers 402 with PAYMENT-REQUIRED: price, network, and payTo set to the Gage vault. extra.gage names the verifier, the provider and the schema hash the tool commits to.
2. Pay with an expectation. The agent signs a payment to the vault and retries with PAYMENT-SIGNATURE and GAGE-EXPECT: the hash of the request it is sending, the quote it accepted, the schema it wants.
3. Hold. The tool forwards both to POST /settle. The verifier collects the payment into the vault and opens a hold with a timeout. Nobody can spend it yet.
4. Deliver. The tool runs its handler and reports the response to POST /holds/:id/deliver: status, body, the request hash it processed, the price it charged.
5. Verdict. Five checks, in order, stop at the first failure. Pass: released to the provider minus the fee. Fail: refunded to the agent in full. No report before the timeout: refunded, even if the verifier is down.

Headers

All four carry base64(JSON). Decode, parse, done.

CORS exposes PAYMENT-REQUIRED and PAYMENT-RESPONSE, so a browser agent can read them.

Endpoints

Base URL . The first three are shaped like an x402 facilitator (/supported, /verify, /settle); the rest are Gage's holds, registry and counters. Buttons run live against this verifier.

POST /settle
{
  "paymentPayload":      PaymentPayload,        // decoded PAYMENT-SIGNATURE
  "paymentRequirements": PaymentRequirements,   // the terms from your 402
  "expectation":         Expectation            // decoded GAGE-EXPECT
}

200 { "success": true, "holdId": "42", "payer": "<agent pubkey>", "transaction": "<sig, chain modes>", "network": "..." }
402 { "success": false, "errorReason": "payTo must be the Gage vault" | "missing expectation" | "payment expired" | "insufficient balance" | ..., "network": "..." }

POST /holds/42/deliver
{
  "status": 200,
  "contentType": "application/json",
  "body": "{\"query\":\"solana\",\"results\":[{\"title\":\"…\",\"url\":\"https://…\"}]}",
  "requestHash": "<sha256, see Hashes>",    // of the request you actually processed
  "priceCharged": "10000"                       // what you bill, atomic units
}

200 { "verdict": Verdict }
409 { "error": "hold is refunded" | "hold is expired" }     // already settled, nothing to do
404 { "error": "unknown hold" }

curl -X POST /demo/run -H "content-type: application/json" -d '{"outcome":"price"}'

{ "outcome": "price",
  "steps": [ { "t": 0.5, "label": "request sent", "detail": "GET /v1/search?q=…" }, … ],
  "requirements": PaymentRequirements, "payment": PaymentPayload,
  "verdict": { "pass": false, "failed": "price", "checks": [ … ], "action": "refunded", … },
  "response": { "status": 200, … }, "totalMs": 31 }

Objects

PaymentRequirements

One entry of accepts in the 402. Standard x402 v2 fields; Gage adds extra.gage.

PaymentPayload

{ x402Version: 2, scheme: "exact", network, payload }. On the local ledger, payload is { kind: "local", from, to, asset, amount, nonce, validUntil, signature }: an ed25519 signature by from over the canonical JSON of the other fields. On chain, { kind: "solana", transaction }: a fully signed transaction, base64, either a transferChecked into the vault's token account (custodial mode) or the program's open_hold (anchor mode). signPayment in @gage/agent builds all three.

Expectation

Delivery

{ status, contentType?, body, requestHash, priceCharged }: the provider's report. body is the response as text, exactly what went to the agent.

Verdict

The five checks

In order, stop at the first failure, nothing subjective, nothing stored but hashes. Anyone with the same inputs recomputes the same verdict.

Hashes

All sha256, hex. Compute them yourself to recompute any verdict.

requestHash = sha256( METHOD + "\n" + path + search + "\n" + sha256(body) )
                // METHOD upper-case, path and query from the URL, body "" for GET
bodyHash    = sha256( canonicalJSON(body) )   // JSON bodies: keys sorted, no whitespace, so re-serialising is not a new answer
            = sha256( body )                  // anything else
schemaHash  = sha256( canonicalJSON(schema) )

Sandbox

This deployment ships a breakable tool: a paid search endpoint that misbehaves on demand. Point your agent at it to see every verdict before you touch a real tool.

GET /v1/search?q=solana                // 402 with Gage terms, then a proper answer
GET /v1/search?q=solana&outcome=empty  // empty · schema · price · dup · drift

The console runs the same scenarios with the verifier's own agent and shows every hold, check and event as they happen.

Settlement modes

/info tells you which one a verifier runs. The HTTP surface is the same; what changes is the payment the agent signs and where the money sits.

Errors