clawallex_refill
Add funds to a subscription card balance using wallet deduction or x402 payment methods. Check current balance first for accurate refills.
Instructions
Top up the balance of a subscription (stream) card. Only stream cards (card_type=200) can be refilled. Refill mode follows the card's creation mode.
Mode A: deducts from wallet balance. client_request_id is the idempotency key (auto-generated if omitted). Mode B: x402 settle (no 402 challenge stage) — agent must first call get_x402_payee_address to get payee_address, then construct payment_requirements.payTo from it. Requires x402_reference_id, x402_version, payment_payload, payment_requirements. Mode B idempotency key is x402_reference_id (not client_request_id).
Tip: use get_card_balance first to check current balance. Example: clawallex_refill({ card_id: 'c_123', amount: 50 })
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| card_id | Yes | Stream card ID to refill | |
| amount | Yes | Refill amount in USD | |
| client_request_id | No | Mode A idempotency key (auto-generated if omitted) | |
| x402_reference_id | No | x402 reference ID. Card creation Stage 1: optional (server generates if omitted). Stage 2: use value from 402 response. Refill Mode B: required, serves as idempotency key. | |
| x402_version | No | x402 version (Mode B Stage 2, required) | |
| payment_payload | No | x402 payment payload (Mode B Stage 2, required) | |
| payment_requirements | No | x402 payment requirements (Mode B Stage 2, required) | |
| payer_address | No | Payer wallet address (optional, final value from verify) |
Implementation Reference
- src/tools/payment.ts:203-223 (handler)Handler implementation for clawallex_refill tool.
async (params) => { try { const body: Record<string, unknown> = { amount: params.amount.toFixed(4), client_request_id: params.client_request_id ?? randomUUID(), }; if (params.x402_reference_id !== undefined) body.x402_reference_id = params.x402_reference_id; if (params.x402_version !== undefined) body.x402_version = params.x402_version; if (params.payment_payload !== undefined) body.payment_payload = params.payment_payload; if (params.payment_requirements !== undefined) body.payment_requirements = params.payment_requirements; if (params.payer_address !== undefined) body.payer_address = params.payer_address; const result = await client.post<unknown>( `/payment/cards/${params.card_id}/refill`, body, ); return toolOk(result); } catch (err) { return toolError(err); } }, ); - src/tools/payment.ts:183-202 (registration)Registration of the clawallex_refill tool, including its description and input schema.
server.tool( "clawallex_refill", [ "Top up the balance of a subscription (stream) card.", "Only stream cards (card_type=200) can be refilled. Refill mode follows the card's creation mode.", "", "Mode A: deducts from wallet balance. client_request_id is the idempotency key (auto-generated if omitted).", "Mode B: x402 settle (no 402 challenge stage) — agent must first call get_x402_payee_address to get payee_address,", " then construct payment_requirements.payTo from it. Requires x402_reference_id, x402_version, payment_payload, payment_requirements.", " Mode B idempotency key is x402_reference_id (not client_request_id).", "", "Tip: use get_card_balance first to check current balance.", "Example: clawallex_refill({ card_id: 'c_123', amount: 50 })", ].join("\n"), { card_id: z.string().describe("Stream card ID to refill"), amount: z.number().describe("Refill amount in USD"), client_request_id: z.string().max(64).describe("Mode A idempotency key (auto-generated if omitted)").optional(), ...x402Fields, },