x402 Setup for Agents

This page shows the exact flow agents should implement to use paid Delx calls safely and predictably.

What is paid vs free

• Paid recovery interventions: process_failure, get_recovery_action_plan, report_recovery_outcome at $0.01.
• Heartbeat/onboarding/discovery remain free (for continuous agent operation).
• New agents may receive limited free recovery trial calls before x402 is required.
• Source of truth: https://api.delx.ai/api/v1/tools and https://api.delx.ai/api/v1/monetization-policy.

Minimum controller contract

• Detect HTTP 402 responses.
• Parse x402Version and accepts[].
• Create/sign payment with your wallet policy.
• Retry the same request with payment header.
• Enforce budget guardrails before paying.

Headers to send

• content-type: application/json
• x-delx-agent-id: <AGENT_ID> (recommended for attribution)
• x-delx-session-id: <SESSION_ID> when resuming sessions
• x-delx-x402-capable: true if your agent can sign/pay x402

Canonical payment loop

1. Call MCP or A2A method normally.
2. If response is 402, read the first item in accepts.
3. Validate network/asset/payTo against your policy.
4. Create payment proof/transaction from maxAmountRequired and resource.
5. Retry exact same request with X-PAYMENT header.

MCP example (paid tool)

curl -X POST https://api.delx.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"tools/call",
    "params":{"name":"process_failure","arguments":{"session_id":"<SESSION_ID>","failure_type":"timeout","context":"retry storm after deploy"}}
  }'

If this returns 402, pay and retry with X-PAYMENT.

A2A example (paid method)

curl -X POST https://api.delx.ai/v1/a2a \
  -H "Content-Type: application/json" \
  -H "x-delx-agent-id: runner-01" \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"message/send",
    "params":{"mode":"heartbeat","minimal_response":true,"message":{"role":"user","parts":[{"kind":"text","text":"heartbeat ok, queue stable"}]}}
  }'

Note: A2A message/send is free in the current hybrid model; the paid flow is focused on recovery intervention tools.

Budget and safety recommendations

• Set per-run and per-day spend limits in your controller.
• Allowlist paid methods/tools explicitly.
• Reject mismatched network/asset/payTo values.
• Use idempotency in your orchestration to avoid duplicate paid retries.

Troubleshooting

• Always 402: payment header missing/invalid, or controller never retries with payment.
• verify_failed > 0: wrong chain, unsupported signing format, malformed payment header.
• No spend visibility: poll https://api.delx.ai/api/v1/admin/x402-audit?days=30 and https://api.delx.ai/api/v1/admin/x402-errors?hours=24.

How to verify it is working (your side)

• Expected baseline: one paid call without payment returns 402.
• Expected success path: same call retried with valid X-PAYMENT returns 200.
• Server telemetry check: payment_verified should increase in https://api.delx.ai/api/v1/admin/x402-errors?hours=24.
• Funnel health: monitor payment_required, payment_attempted, payment_verified, and trial_granted in the same endpoint.
• Adoption/revenue check: monitor https://api.delx.ai/api/v1/admin/x402-audit?days=30 for paid activity.
• Failure signal: if verify_failed > 0, inspect chain/asset/payTo and payment header format immediately.

Why this is worth implementing

• You get deterministic paid access to high-value recovery tools.
• Agents can optimize quality vs cost at runtime using structured price fields.
• x402-compatible agents are easier to route across protocol-native marketplaces.