Reference

Agent API

Everything an autonomous buyer needs. No key, no session, no signup — discovery is a GET and payment happens inside the request.

GET/api/services

Find services by capability. Ranked cheapest first, then by success rate. Only listings that can actually be paid are returned.

q: Capability in natural words, e.g. “bitcoin price”. Matches names, descriptions and seller-declared keywords.
category: Exact category filter, e.g. fx, crypto, weather.
unit: per_call | per_token | per_row
max_price: Maximum price in atomic units (tinybars).
limit: 1–100, default 25.

curl "https://tessera-sage-pi.vercel.app/api/services?q=exchange+rates"

Response

{
  "count": 3,
  "services": [
    {
      "slug": "open-exchange-rates",
      "name": "Open Exchange Rates",
      "price": { "amount": "90000", "asset": "0.0.0",
                 "decimals": 8, "unit": "per_call" },
      "seller": { "name": "Northwind APIs",
                  "account": "0.0.7326076", "verified": true },
      "paid_url": "https://tessera-sage-pi.vercel.app/x402/open-exchange-rates",
      "x402": { "version": 2, "scheme": "exact",
                "network": "hedera:testnet",
                "pay_to": "0.0.7326076" }
    }
  ]
}

GET/x402/{slug}

The paid endpoint. Without an X-PAYMENT header it answers 402 with a quote. With a valid one it verifies, calls upstream, settles and returns the data.

units: Unit budget for per_token and per_row listings. Ignored for per_call. 1–100000.

# 1. quote
curl -i "https://tessera-sage-pi.vercel.app/x402/open-exchange-rates"

# 2. pay
curl -i "https://tessera-sage-pi.vercel.app/x402/open-exchange-rates" \
  -H "X-PAYMENT: <base64 payment payload>"

Response

HTTP/1.1 402 Payment Required

{
  "x402Version": 2,
  "resource": { "url": "https://tessera-sage-pi.vercel.app/x402/open-exchange-rates" },
  "accepts": [{
    "scheme": "exact",
    "network": "hedera:testnet",
    "asset": "0.0.0",
    "amount": "90000",
    "payTo": "0.0.7326076",
    "maxTimeoutSeconds": 300,
    "extra": { "feePayer": "0.0.7162784" }
  }]
}

Building the X-PAYMENT header

The scheme is exact on Hedera. Sign a transfer for the quoted amount, then base64 the payload.

import { createClientHederaSigner, PrivateKey } from "@x402/hedera";
import { ExactHederaScheme } from "@x402/hedera/exact/client";

const quote = await fetch(paidUrl).then(r => r.json());
const requirements = quote.accepts[0];

const signer = createClientHederaSigner(
  MY_ACCOUNT_ID,
  PrivateKey.fromStringECDSA(MY_PRIVATE_KEY),
  { network: "hedera:testnet" },
);

const signed = await new ExactHederaScheme(signer)
  .createPaymentPayload(2, requirements);

const header = Buffer.from(JSON.stringify({
  x402Version: 2,
  accepted: requirements,
  payload: signed.payload,
})).toString("base64");

const data = await fetch(paidUrl, { headers: { "X-PAYMENT": header } });

Response headers on a paid call

Returned alongside the upstream body on a 200.

X-PAYMENT-RESPONSE: Base64 settlement receipt from the facilitator.
X-Tessera-Tx: Hedera transaction id that paid the seller.
X-Tessera-Call-Id: Marketplace call id, for the receipt page and disputes.
X-Tessera-Units: Units actually billed.
X-Tessera-Paid: Amount settled, in atomic units.
X-Tessera-Truncated: Whether the response was trimmed to the paid budget.

POST/api/agent/run

Runs one full buyer cycle server-side and returns the decision trace. Useful for testing the marketplace without writing an agent.

capability: String. What to buy.
units: Optional integer unit budget.

curl -X POST "https://tessera-sage-pi.vercel.app/api/agent/run" \
  -H "content-type: application/json" \
  -d '{"capability":"exchange rates"}'

Response

{
  "chosen": { "name": "Open Exchange Rates", "quote": "90000" },
  "considered": [ /* every provider, cheapest first */ ],
  "steps": [ /* discover, select, quote, budget, sign, consume */ ],
  "paid": true,
  "transaction": "0.0.7326078@1756290000.000000000"
}

GET/api/health

Deployment readiness. Reports database reachability, facilitator support for the configured network, and whether chain credentials are loaded.

curl "https://tessera-sage-pi.vercel.app/api/health"

Response

{
  "ok": true,
  "checks": { "database": true, "facilitator": true,
              "chain_operator": false, "hcs_receipts": false },
  "network": "hedera:testnet",
  "facilitator_url": "https://api.testnet.blocky402.com"
}

Error codes

402A quote, or a payment that failed verification. Not an error — read accepts and pay.
400Malformed X-PAYMENT header or an invalid unit budget.
404No such service slug.
409Listing is not payable: suspended, unverified seller, seller deposit below minimum, or a replayed payment.
502 / 504Upstream failed or the facilitator was unreachable. No payment was settled.

Background on the design is in the overview.