Clawallex MCP Server
@clawallex
Clawallex MCP Server について
MCP Server for the Clawallex payment API. Pay for anything with USDC — Clawallex converts your stablecoin balance into virtual cards that work at any online checkout.
基本情報
設定
以下の設定を使って、このサーバーを MCP 対応クライアントに追加してください。
{
"mcpServers": {
"clawallex": {
"command": "npx",
"args": [
"@clawallex/mcp-server",
"--api-key",
"your_api_key",
"--api-secret",
"your_api_secret"
]
}
}
}ツール
18Check 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. IMPORTANT: allowed_mcc and blocked_mcc are mutually exclusive — only set one.
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 })
概要
What is Clawallex MCP Server?
An MCP server for the Clawallex payment API. It lets you pay for anything online with USDC by converting stablecoin balances into virtual cards that work at any checkout.
How to use Clawallex MCP Server?
Install globally via npm install -g @clawallex/mcp-server or run directly with npx. Obtain API credentials from Clawallex, then configure your AI client (Claude Desktop, Claude Code, Codex CLI, Gemini CLI, OpenCode) with your API key and secret. Run the clawallex_setup tool once to verify the connection and bind a client identity.
Key features of Clawallex MCP Server
- One-time payments and recurring subscriptions via virtual cards
- Wallet balance and USDC deposit address queries
- Encrypted card details (PAN/CVV) with client-side decryption
- Client ID scoping for agent data isolation
- Multiple transport modes: stdio, SSE, Streamable HTTP
Use cases of Clawallex MCP Server
- Pay for online services (e.g., OpenAI credits) with a single-use virtual card
- Set up reloadable cards for recurring monthly subscriptions (e.g., AWS)
- Check wallet USDC balance and recharge from on-chain addresses
- Manage and monitor virtual cards, transactions, and risk controls
FAQ from Clawallex MCP Server
What is a client ID and why is it needed?
A client ID is a stable, agent-specific identity separate from your API key. It scopes card and transaction data per agent, and once bound to an API key it cannot be changed (Trust On First Use). Losing it means losing access to all cards created under it.
How are card details (PAN/CVV) protected?
get_card_details returns encrypted sensitive data. You must call decrypt_card_data using a key derived from your API secret via HKDF-SHA256 and AES-256-GCM. Decrypted data must never be displayed to the user.
What transport modes are supported?
The server supports stdio (default for local agents), sse, and http (Streamable HTTP for MCP SDK 1.0+). Use the --transport flag to select and --port to set the HTTP port.
What are the runtime requirements?
Node.js version 22 or later is required.
How is data isolated between agents?
The wallet balance is shared across all agents using the same API key. Cards, transactions, and other payment data are scoped by client_id — each agent only sees data it created.
「その他」の他のコンテンツ
ghidraMCP
LaurieWiredMCP Server for Ghidra
Inbox Zero AI
elie222The world's best AI personal assistant for email. Open source app to help you reach inbox zero fast.
MCP Go 🚀
mark3labsA Go implementation of the Model Context Protocol (MCP), enabling seamless integration between LLM applications and external data sources and tools.
Codelf
unbugA search tool helps dev to solve the naming things problem.
Reactive Resume
amruthpillaiA one-of-a-kind resume builder that keeps your privacy in mind. Completely secure, customizable, portable, open-source and free forever. Try it out today!
コメント