Execute Paid X402 Capability
x402_execute_capabilityExecute one priced HTTP 402 capability through the Stripe X402 Hub, debiting exact USD cents from a prepaid spend key and returning the upstream payload, credit receipt, and Ed25519 cryptographic execution attestation. Use this only after confirming capability_id via x402_list_capabilities and verifying pricing via x402_quote_plan; do not use this for price quotes (use x402_quote_plan). Charges prepaid USD credit (pass max_spend_cents as a hard caller ceiling and idempotency_key for safe retries); failed upstream calls (HTTP >= 400) automatically refund credit and restore delegate budgets. Pass approval_id (sba_*) after x402_decide_approval approves an over-cap request. Returns 401/402/403 if the key is missing, underfunded, frozen, or over policy cap.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"capability_id": "<capability_id>"
},
"name": "x402_execute_capability"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| arguments | No | JSON input arguments expected by the target capability (e.g. {"destination": "annapolis"} for reality_harbor_state or {"query": "city dock"} for kb_search). | |
| spend_key | No | Stripe-funded master or delegated subagent spend key (format: sbk_<43+ chars>). Optional when the caller supplies the x-atlas-spend-key HTTP header. | |
| approval_id | No | Single-use human spend escalation approval ticket identifier returned by x402_request_approval (format: sba_<16 hex chars>, e.g. sba_aabbccddeeff0011). | |
| capability_id | Yes | Priced capability identifier or route from x402_list_capabilities to execute (e.g. "reality_harbor_state", "kb_search", or "POST /switchboard/chunk"). | |
| idempotency_key | No | Stripe-standard idempotency key (8-128 chars, e.g. "run-2026-11-22-harbor-01") ensuring retries reuse the exact original reservation without double-charging. | |
| max_spend_cents | No | Hard client-side spend ceiling in USD cents (e.g. 50 = $0.50). If the live capability price exceeds this value, execution aborts with HTTP 403 before any debit occurs. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ok | Yes | True when the capability executed and settled cleanly. | |
| result | No | Upstream JSON payload returned by the executed capability. | |
| schema | No | Execution envelope schema (atlas.x402.center_execution.v1). | |
| credit_receipt | No | Settled Stripe prepaid credit receipt. | |
| execution_attestation | No | Detached Ed25519 JWS cryptographic attestation binding request, response, and settlement. |