Build with
Tollex

import { TollexClient, TollexTools, usdg, type AgentPolicyProfile } from "@tollex/client";
import { PolicyEngine } from "@tollex/policy";
import { verifyReceipt } from "@tollex/receipts";

const client = new TollexClient({
  wallet, // a viem account or a remote signer; the key never leaves it
  policy: new PolicyEngine({
    id: "research-policy",
    agentId: "research-03",
    networks: [NETWORK],
    assets: [{ network: NETWORK, address: USDG_ADDRESS, decimals: 6 }],
    schemes: ["exact"],
    maxPerRequest: usdg("0.01"),
    budgets: { daily: usdg("5") },
  }),
  requireReceipt: true,
});
const tollex = new TollexTools(client, TOLLEX_URL);

const plan = await tollex.resolve({
  need: "token balance of a wallet",
  input: { address: wallet.address },
  constraints: { maxCost: usdg("0.001"), receiptRequired: true },
});

plan.selected?.toolId; // the capability that would be bought
plan.plan.reasons; // why it won, in plain language
plan.plan.rejectedBy; // e.g. { PRICE_LIMIT: 9, NOT_RELEVANT: 21 }

const response = await fetch(`${TOLLEX_URL}/v1/resolve`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    need: "spot price for a trading pair",
    input: { pair: "ETH-USD" },
    constraints: { maxCost: "5000", receiptRequired: true }, // atomic units: 0.005 USDG
    quote: true,
  }),
});
const { resolutionId, plan, quote, execute } = await response.json();
// plan.selected, plan.evaluations[].rejections, plan.ranking.formula
// execute: { url, method, headers } to call with an x402 client

TOLLEX_URL=https://your-tollex-host \
TOLLEX_POLICY_FILE=./policy.json \
TOLLEX_WALLET_KEY_FILE=./payer.key \
tollex mcp

POST /a2a
A2A-Version: 1.0

{ "jsonrpc": "2.0", "id": 1, "method": "SendMessage",
  "params": { "message": { "messageId": "m-1", "role": "ROLE_USER",
    "parts": [{ "data": { "toolId": "chain_get_block", "input": {} } }] } } }

// The task comes back in TASK_STATE_INPUT_REQUIRED with
// metadata["x402.payment.required"]. Send the same message again with
// metadata["x402.payment.payload"] to pay; the result arrives as an artifact.

app.post(
  "/v1/forecast",
  paywall.protect({
    id: "forecast",
    description: "Seven-day demand forecast for a SKU",
    scheme: "exact",
    amount: usdg("0.002"),
    inputSchema: { type: "object", properties: { sku: { type: "string" } }, required: ["sku"] },
    tags: ["forecast", "retail"],
  }),
  async (c) => c.json({ sku: (await c.req.json()).sku, days: [12, 14, 11, 9, 15, 18, 16] }),
);

const manifest: ProviderManifestInput = {
  id: "acme.marketdata",
  name: "Acme market data",
  baseUrl: "https://api.acme-data.example/v2",
  network: NETWORK,
  asset: { address: USDG_ADDRESS, symbol: "USDG" },
  source: "provider manifest v3, reviewed 2026-10-02",
  // A reference, never the key itself. The operator resolves it at call time.
  auth: [{ kind: "API_KEY_HEADER", name: "key", param: "X-Api-Key", secretRef: "env:ACME_API_KEY" }],
  endpoints: [
    {
      id: "acme_spot_price",
      name: "Spot price",
      description: "Latest spot price for a trading pair, with the exchange timestamp.",
      method: "GET",
      path: "/spot/{pair}",
      pathParams: ["pair"],
      inputSchema: {
        type: "object",
        properties: { pair: { type: "string", pattern: "^[A-Z]{2,6}-[A-Z]{2,6}$" } },
        required: ["pair"],
        additionalProperties: false,
      },
      price: 2_000n, // atomic USDG per successful call (0.002 USDG)
      tags: ["market", "price", "spot"],
      category: "market",
    },
  ],
};
const provider = new ManifestToolProvider(manifest, { secrets: new DefaultSecretResolver() });

const res = await fetch(`${TOLLEX_URL}/.well-known/tollex-receipt-keys`);
const { keys } = (await res.json()) as { keys: { address: `0x${string}`; status: string }[] };
const check = await verifyReceipt(result.receipt!, {
  trustedSigners: keys.filter((k) => k.status === "active").map((k) => k.address),
});

check.valid; // signature, content hash and bindings all hold
result.receipt!.body.quote?.quoteHash; // the quote this payment was bound to