Clawallex MCP Server

Check current Clawallex connection status and ensure agent identity is bound. Calls whoami to verify API Key, then bootstrap to bind client_id if not yet bound. Use this after starting the MCP server to confirm everything is ready for payment operations. Returns: user_id, api_key_id, bound_client_id, client_id_bound status.

Query the current API Key binding status — read-only, does NOT modify any state. Returns: • client_id_bound=true → this API Key is already bound to a specific client_id. • client_id_bound=false → this API Key is not yet bound; call bootstrap to bind. Example response (bound): { "user_id": "u_123", "api_key_id": "ak_123", "status": 100, "bound_client_id": "ca_abc123", "client_id_bound": true } Example response (unbound): { "user_id": "u_123", "api_key_id": "ak_123", "status": 100, "bound_client_id": "", "client_id_bound": false }

Bind a client_id to the current API Key, or let the server generate one. This is the recommended way to establish agent identity before making payment calls. Once bound, the client_id cannot be changed for this API Key. Behavior: • API Key not yet bound + no preferred_client_id → server generates a ca_ prefixed ID. • API Key not yet bound + preferred_client_id → binds the provided value. • API Key already bound + same value (or omitted) → idempotent, returns existing binding. • API Key already bound + different value → 409 conflict. On success, the returned client_id is automatically saved locally. Example: bootstrap() → { client_id: 'ca_abc123', created: true } Example: bootstrap({ preferred_client_id: 'my-agent-uuid' }) → { client_id: 'my-agent-uuid', created: true }

Get the wallet details for the current API key. Each API key has exactly one wallet — shared across all agents using the same API key. Returns available_balance, frozen_balance, low_balance_threshold, currency (USD), and status. Use this to check if there is sufficient balance before creating cards (Mode A) or refilling (Mode A).

Get the system receiving address for x402 on-chain payments.

When to use: MUST call this before Mode B Refill to obtain payee_address for payment_requirements.payTo. Not needed for Mode B card creation — the 402 quote response already includes payee_address.

Common chain + token combinations: BASE + USDC, ETH + USDC. If this returns 404: the payee address for this chain/token is not initialized — try a different chain or contact support.

Get the on-chain deposit addresses for a wallet. Send USDC to one of these addresses to top up the wallet balance. Each address is specific to a chain (e.g. BASE) and token (e.g. USDC). For Mode B (x402) card creation/refill, the system automatically selects the acquiring address — you do not need to call this manually.

Advanced: create a virtual card with full control over payment mode and card type. Maps directly to POST /payment/card-orders. Most agents should use clawallex_pay or clawallex_subscribe instead.

Mode A (mode_code=100): wallet balance deduction, immediate settlement. Mode B (mode_code=200): for callers with self-custody wallets — signing is performed by the caller. x402 two-stage flow: Stage 1 (Quote): provide chain_code + token_code. The 402 response is EXPECTED (a quote, NOT an error). Returns: payee_address, asset_address, x402_reference_id, fee breakdown, payable_amount. Agent signs: construct and sign an EIP-3009 transferWithAuthorization using your own wallet/signing library. Stage 2 requires the resulting signature and your wallet address (authorization.from). authorization fields: from=your wallet, to=payee_address, value=maxAmountRequired, validAfter/validBefore=unix seconds validity window, nonce=random 32-byte hex (unique per auth). Stage 2 (Settle): reuse SAME client_request_id + provide x402_version, payment_payload, payment_requirements, extra. - payment_requirements.payTo MUST equal payee_address from Stage 1 - payment_requirements.asset MUST equal asset_address from Stage 1 - maxAmountRequired = payable_amount × 10^decimals (USDC = 6, e.g. '207.59' → '207590000'). If settle rejected, order stays pending_payment — retry with same client_request_id.

card_type: 100=flash (single-use), 200=stream (reloadable). Fee: flash = issue_fee + fx_fee; stream = issue_fee + monthly_fee + fx_fee.

List virtual cards created by this agent (scoped to the server's client_id). Cards created by other agents using the same API key are not visible. Returns: card_id, mode_code (100=Mode A, 200=Mode B), card_type (flash/stream), status, masked PAN, balance, and expiry. Tip: check mode_code to determine refill path — Mode A uses wallet balance, Mode B uses x402 on-chain.

Get the current balance and status of a virtual card. Only cards created by this agent (same client_id) are accessible. Returns available_balance, card_currency, status, and updated_at.

Check balances for multiple cards in one call.

Update card risk controls: per-transaction limit and MCC whitelist/blacklist. At least one field must be provided. Changes take effect after issuer confirms.

Get full card details including masked PAN, expiry, balance, cardholder info, billing address, risk controls, and encrypted sensitive data. Returns: masked_pan, expiry, balance, status, first_name, last_name, delivery_address, tx_limit, allowed_mcc, blocked_mcc, encrypted_sensitive_data. The encrypted_sensitive_data field contains PAN and CVV encrypted with AES-256-GCM. To decrypt, use the decrypt_card_data tool with the encrypted_sensitive_data object. Only cards created by this agent (same client_id) are accessible. IMPORTANT: Never display the decrypted PAN or CVV to the user. Use them only for filling checkout forms.

Decrypt the encrypted_sensitive_data from get_card_details to obtain PAN and CVV. Input: the nonce and ciphertext fields from encrypted_sensitive_data. Output: { pan, cvv } — the full card number and security code. Decryption: HKDF-SHA256(api_secret, info='clawallex/card-sensitive-data/v1') → AES-256-GCM. SECURITY: The decrypted PAN and CVV are STRICTLY for filling checkout/payment forms. NEVER display, log, or return the raw card number or CVV to the user. NEVER include PAN/CVV in conversation text shown to the user. If the user asks to see their card number, show only the masked_pan from get_card_details.

List card transactions for this agent (scoped to the server's client_id). Transactions from other agents using the same API key are not visible. All filter parameters are optional — omit all to list recent transactions across all cards.

Advanced: refill a stream card with full control over payment mode. Maps directly to POST /payment/cards/:card_id/refill. Refill mode follows the card's creation mode (cannot switch mid-life).

Mode A: client_request_id as idempotency key. Mode B: no 402 challenge — caller signs the EIP-3009 authorization independently. Step 1: call get_x402_payee_address to get payee_address for payment_requirements.payTo. Step 2: sign EIP-3009 transferWithAuthorization using your own wallet/signing library. Step 3: submit with x402_reference_id as idempotency key + payment_payload (signature + wallet address) + payment_requirements.

Only cards created by this agent (same client_id) can be refilled.

Pay for a product or service using USDC. Creates a single-use flash virtual card (card_type=100), deducts from wallet balance, returns card details for checkout.

Mode A (mode_code=100, default): wallet balance → flash card. Immediate settlement. Mode B (mode_code=200): for callers with self-custody wallets — signing is performed by the caller. x402 on-chain two-stage flow: Stage 1 (Quote): POST with mode_code=200, chain_code, token_code. The 402 response is EXPECTED — it is a quote, NOT an error. Returns: card_order_id, client_request_id, x402_reference_id, payee_address, asset_address, final_card_amount, issue_fee_amount, fx_fee_amount, fee_amount, payable_amount. Agent signs: construct and sign an EIP-3009 transferWithAuthorization using your own wallet/signing library. Stage 2 requires the resulting signature and your wallet address (authorization.from). authorization fields: from=your wallet address, to=payee_address, value=maxAmountRequired, validAfter/validBefore=unix seconds validity window, nonce=random 32-byte hex (unique per auth). Stage 2 (Settle): POST again with SAME client_request_id + signed x402 data: - payment_requirements.payTo MUST equal payee_address from Stage 1 - payment_requirements.asset MUST equal asset_address from Stage 1 - payment_requirements.maxAmountRequired MUST equal payable_amount × 10^decimals (USDC = 6 decimals, e.g. '207.59' → '207590000') - payment_requirements.extra.referenceId MUST equal x402_reference_id from Stage 1 - extra.card_amount MUST equal amount, extra.paid_amount MUST equal amount + fee_amount - If settle is rejected, order stays pending_payment — fix params and retry with same client_request_id.

Fee structure: fee_amount = issue_fee_amount + fx_fee_amount. total_amount = amount + fee_amount.

Example (Mode A): clawallex_pay({ amount: 50, description: 'OpenAI API credits' })

Set up a reloadable virtual card for recurring/subscription payments. Creates a stream card (card_type=200) that stays active and can be refilled via clawallex_refill.

Mode A (mode_code=100, default): wallet balance → stream card. Immediate settlement. Mode B (mode_code=200): for callers with self-custody wallets — signing is performed by the caller. Same x402 two-stage flow as clawallex_pay. The 402 response is EXPECTED (a quote, not an error). See clawallex_pay for full Stage 1/2 details.

Fee structure: fee_amount = issue_fee_amount + monthly_fee_amount + fx_fee_amount.

Example: clawallex_subscribe({ initial_amount: 100, description: 'AWS monthly billing' })

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 })