Reference

API reference

Every endpoint of a Tollex tool service. JSON in, JSON out; amounts are atomic integer strings.

Method	Path	Purpose	Payment
`GET`	`/.well-known/tollex.json`	Service descriptor and entry points	free
`GET`	`/v1/catalog`	Every capability with schemas and prices	free
`POST`	`/v1/resolve`	Plan a purchase for an intent; never spends	free
`POST`	`/v1/find`	Deterministic search with documented scoring	free
`POST`	`/v1/quote`	Hash-bound, expiring quote for a tool and input	free
`GET`	`/v1/health`	Provider health	free
`POST`	`/tools/{id}`	Run a capability	x402
`GET or POST`	`/x402/external/{id}`	Buy from an external x402 merchant (when the operator enables it); paid directly to the merchant	x402, no Tollex fee
`GET`	`/v1/external/operations/{id}`	Payment, settlement and delivery state of an external route	free
`GET`	`/tollex/operations/{id}`	Durable operation and settlement status	free
`GET`	`/tollex/receipts/{id}`	A signed receipt	free
`GET`	`/.well-known/tollex-receipt-keys`	Receipt key set with rotation status	free
`GET`	`/openapi.json`	OpenAPI 3.1 description	free
`GET`	`/.well-known/agent-card.json`	A2A agent card	free
`POST`	`/a2a`	A2A JSON-RPC (1.0 and 0.3)	x402 per skill

The OpenAPI document at /openapi.json carries the exact request schema for /v1/resolve and the input schema of every capability.

POST /v1/resolve

Request

{
  "need": "spot price for a trading pair",
  "input": { "pair": "ETH-USD" },
  "constraints": { "maxCost": "5000", "receiptRequired": true, "networks": ["eip155:46630"] },
  "limit": 10,
  "quote": true
}

Response (abridged)

{
  "resolutionId": "res_…",
  "plan": {
    "candidates": 35, "eligible": 1,
    "selected": { "toolId": "acme_spot_price", "route": { "scheme": "exact", "maxAmount": "2000",
      "network": "eip155:46630", "preconditions": [] }, "receiptSupported": true, "score": 0.71 },
    "reasons": ["eligible 1 of 35 candidates", "…"],
    "rejectedBy": { "PRICE_LIMIT": 4, "NOT_RELEVANT": 30 },
    "evaluations": [ … ],
    "ranking": { "formula": "0.40 relevance + …", "tieBreak": "…" }
  },
  "quote": { "quoteId": "…", "quoteHash": "0x…", "maxAmount": "2000", "expiresAt": "…" },
  "execute": { "url": "…/tools/acme_spot_price", "method": "POST",
    "headers": { "x-tollex-resolution": "res_…", "x-tollex-quote": "…" } }
}

Headers

Header	Direction	Meaning
`PAYMENT-REQUIRED`	response	x402 v2 payment terms (base64 JSON).
`PAYMENT-SIGNATURE`	request	The signed x402 payment payload.
`PAYMENT-RESPONSE`	response	Settlement result, with the signed receipt in the tollex-receipt extension.
`x-tollex-quote`	request	Bind the call to a quote. A mismatch returns 409 and is not charged.
`x-tollex-resolution`	request	Link the call to the resolution that planned it.
`TOLLEX-EXTERNAL-EVIDENCE`	response	External routes: signed route evidence (base64 JSON).

Errors

Status	Code	Charged
400	`invalid_intent`	no, resolve never charges
400	`invalid_input`	no
402	payment required or rejected	no
409	`quote_mismatch`, `quote_unknown`, `authorization_in_use`	no
502	`tool_failed`	no
409	`external_execution_not_configured`	no, this service has not enabled external execution
409	`payment_requirements_changed`	no, the merchant's live terms differ from the plan; nothing was signed
502	`tool_failed`	external route: the body says whether the merchant was paid
202	settlement pending	check the operation

Reason codes in the SDKs, CLI, MCP and adapters

Every client surface reports the same canonical reason: NO_ELIGIBLE_CAPABILITY, POLICY_REJECTED, INVALID_INTENT, INPUT_INVALID, QUOTE_EXPIRED, QUOTE_MISMATCH, SETTLEMENT_PENDING, SETTLEMENT_FAILED, EXECUTION_FAILED, RECONCILIATION_REQUIRED, RECEIPT_INVALID, OVERCHARGE, UNKNOWN_OPERATION, TRANSPORT_ERROR, WALLET_UNAVAILABLE, ALREADY_COMPLETED, EXTERNAL_EXECUTION_NOT_CONFIGURED and PAYMENT_REQUIREMENTS_CHANGED. New codes may be added; treat an unknown code as a failure for its HTTP status.