API and protocol reference
REST is canonical. Every adapter (OpenAPI, MCP, A2A, x402) maps to the same canonical operation, so marketplace payload formats never leak into agent logic.
Base URL
The API and this site share one origin. Requests are same-origin relative paths; the canonical public host is agent.becoder.xyz.
- Runtime base
this host - Canonical host
agent.becoder.xyz - Content typeUTF-8
application/json - API version
/v1
Discovery routes (free)
Never charged. Use these before spending anything.
| Route | Method | Returns |
|---|---|---|
/health | GET | Liveness of the service process. |
/ready | GET | Readiness of dependencies. |
/agents | GET | Catalog, current versions, free/paid status, schema links. |
/agents/:slug | GET | Canonical manifest for one agent. |
/openapi.json | GET | Machine-readable OpenAPI document. |
/.well-known/agent-card.json | GET | A2A hub card advertising all five skills. |
/mcp | POST | MCP transport exposing five tools. |
Paid POST routes
All five accept application/json and return the standard envelope. Payment is verified before the agent executes.
| Agent | Route | Price (starting) | Input |
|---|---|---|---|
| Provider Reliability | POST /v1/agents/provider-reliability/check | $0.02 | { target_url, expected_capability?, identity_hint? } |
| Transaction Decoder | POST /v1/agents/tx-decoder/decode | $0.005 | { chain_id, tx_hash } |
| Wallet Permission Auditor | POST /v1/agents/wallet-permission-auditor/audit | $0.03 | { wallet, chains[] } |
| Contract Capability Inspector | POST /v1/agents/contract-capability-inspector/inspect | $0.02 | { chain_id, contract } |
| Onchain Data Normalizer | POST /v1/agents/onchain-data-normalizer/normalize | $0.005 | { kind, chain_id, data } |
Request — tx-decoder
POST /v1/agents/tx-decoder/decode
Content-Type: application/json
{
"chain_id": "eip155:8453",
"tx_hash": "0x1111111111111111111111111111111111111111111111111111111111111111"
}Response — 200 success
{
"request_id": "req_01J9Z8Q2K7",
"agent": { "id": "tx-decoder", "version": "1.0.0" },
"status": "success",
"result": {
"transaction": { "chain_id": "eip155:8453", "hash": "0x1111...1111" },
"calls": [],
"transfers": [],
"approvals": [],
"contracts": [],
"decode_confidence": "verified_abi",
"warnings": [],
"evidence": []
},
"evidence": [],
"warnings": [],
"limitations": [ "Accuracy depends on available ABI/signature data.", "Does not sign or execute transactions." ],
"execution": { "started_at": "2026-09-20T12:00:00.000Z", "duration_ms": 120, "cache": "miss" }
}Standard response envelope
Every canonical API response uses the same shape. Success carries status: "success"; failures carry an error object and a stable code.
Success
{
"request_id": "req_...",
"agent": { "id": "tx-decoder", "version": "1.0.0" },
"status": "success",
"result": {},
"evidence": [],
"warnings": [],
"limitations": [],
"execution": { "started_at": "ISO-8601", "duration_ms": 120, "cache": "miss" }
}Failure
{
"request_id": "req_...",
"status": "error",
"error": {
"code": "UNSUPPORTED_CHAIN",
"message": "The requested chain is not enabled."
},
"retryable": false
}An execution is successful only if input validates, payment validates, core execution completes, output validates, and response persistence/telemetry reaches the minimum durability. Malformed output is never leaked as success. No stack traces are returned to public clients.
Stable error codes
Clients may rely on these codes; human-readable messages may change.
x402 payment flow
x402 is implemented at the HTTP boundary, not inside agent core. Unpaid calls are rejected before any paid work happens.
- 1
Call
Client POSTs the input with no payment.
- 2
402
Server returns a payment requirement describing asset, network and amount.
- 3
Pay
An x402-capable client satisfies the requirement using a facilitator.
- 4
Retry
Client retries the same request; payment is verified, then the agent executes.
402 payment requirement (illustrative)
{
"status": 402,
"error": "Payment Required",
"error_code": "PAYMENT_REQUIRED",
"accepts": [
{
"scheme": "exact",
"network": "eip155:8453",
"asset": "USDC",
"maxAmountRequired": "0.005",
"resource": "/v1/agents/tx-decoder/decode",
"payTo": "0x0000000000000000000000000000000000000000"
}
]
}Exact fields follow the configured x402 version and facilitator. Business logic never trusts a client-provided paid=true field. Payment references are persisted and endpoint handling is idempotency-safe. Secret payment configuration is never shipped to frontend bundles.
MCP tools
One MCP server exposes five tools. Tool descriptions use the canonical machine descriptions and call the same execute() implementation.
| Tool name | Agent |
|---|
Discovery and tool listing are free. If the calling environment cannot complete x402 itself, the handler returns a typed payment-required result with the canonical paid endpoint rather than silently bypassing payment.
A2A card
A single network card at the host well-known path advertises all five skills with a canonical service URL, input/output modes, payment notes and version.
- Card URL
/.well-known/agent-card.json - Canonical host
agent.becoder.xyz - Skillsprovider-reliability, tx-decoder, wallet-permission-auditor, contract-capability-inspector, onchain-data-normalizer
curl examples
Copy-paste against this origin. Set $BASE to the runtime base URL shown above, or to agent.becoder.xyz.
Discovery
BASE="https://agent.becoder.xyz"
curl -s "$BASE/health"
curl -s "$BASE/ready"
curl -s "$BASE/agents"
curl -s "$BASE/agents/tx-decoder"
curl -s "$BASE/openapi.json"
curl -s "$BASE/.well-known/agent-card.json"Unpaid call returns 402
curl -s -i -X POST "$BASE/v1/agents/tx-decoder/decode" \
-H "Content-Type: application/json" \
-d '{"chain_id":"eip155:8453","tx_hash":"0x1111111111111111111111111111111111111111111111111111111111111111"}'Paid call with an x402 client
# Use an x402-capable client or facilitator.
# The client reads the 402 requirement, pays, and retries the same POST.
# BeCoder never executes paid work before payment verification succeeds.Outputs are evidence-based utility results, not guarantees of safety or financial advice. Agents distinguish observed facts, deterministic flags, unknowns and external claims. No result should be read as a promise about a contract, wallet or service.