Clawallex — OpenClaw Plugin

OpenClaw plugin for Clawallex. Pay for anything with USDC — Clawallex converts your stablecoin balance into virtual Visa cards that work at any online checkout.

Quick Start

# Install from npm
openclaw plugins install @clawallex/clawallex

# Restart gateway to apply
openclaw gateway restart

No configuration needed upfront. After installing, just tell your Agent:

"Set up my Clawallex "

The Agent will call clawallex_setup to guide you through connecting your account.

Configuration

Credentials can be provided in three ways (in priority order):

1. Plugin config — set apiKey / apiSecret in OpenClaw plugin settings
2. Setup tool — call clawallex_setup from your Agent, credentials saved to ~/.clawallex/credentials.json
3. Auto-detect — plugin reads saved credentials on next startup

| Field | Required | Description | |-------|----------|-------------| | apiKey | Optional | API Key — can configure later via clawallex_setup | | apiSecret | Optional | API Secret — can configure later via clawallex_setup | | baseUrl | Optional | API base URL (defaults to https://api.clawallex.com) | | clientId | Optional | Agent-level identifier. Auto-managed via /auth/bootstrap if omitted. |

Tools

High-Level (Recommended)

Agent-friendly tools — just describe what you want to pay for.

| Tool | Description | Example | |------|-------------|---------| | clawallex_pay | One-time payment — creates a single-use virtual card | clawallex_pay({ amount: 50, description: "OpenAI API credits" }) | | clawallex_subscribe | Recurring subscription — creates a reloadable card | clawallex_subscribe({ initial_amount: 100, description: "AWS monthly billing" }) | | clawallex_refill | Top up a subscription card balance | clawallex_refill({ card_id: "c_123", amount: 50 }) | | clawallex_setup | Connect your Clawallex account or check config status | clawallex_setup({ action: "connect", api_key: "...", api_secret: "..." }) |

Identity & Binding

| Tool | Description | |------|-------------| | clawallex_whoami | Query current API Key binding status (read-only) | | clawallex_bootstrap | Bind a client_id to this API Key, or let server generate one |

Wallet & Query

| Tool | Description | |------|-------------| | get_wallet | Check wallet balance and status | | get_wallet_recharge_addresses | Get on-chain USDC deposit addresses (Mode A) | | list_cards | List all virtual cards created by this agent | | get_card_balance | Check a card's current balance | | get_card_details | Get card details with encrypted sensitive data | | decrypt_card_data | Decrypt PAN/CVV from get_card_details for checkout | | list_transactions | View transaction history |

Advanced (x402 On-Chain)

For agents that need direct on-chain USDC payment instead of wallet balance deduction.

| Tool | Description | |------|-------------| | get_x402_payee_address | Get the on-chain receiving address for x402 payments | | create_card_order | Create a card with full control (supports Mode B two-stage) | | refill_card | Refill a stream card with x402 or custom idempotency keys |

Setup Flow

1. clawallex_setup({ action: 'connect', api_key: '...', api_secret: '...' })
   ↓ Internally:
   a. GET /auth/whoami            — verify API key, check binding status
   b. POST /auth/bootstrap        — bind client_id (if not yet bound)
   c. Save credentials + client_id locally

You can also check binding status anytime:

clawallex_whoami()
→ { user_id: "u_123", bound_client_id: "ca_abc123", client_id_bound: true }

Typical Flow (Mode A — Wallet Balance)

1. get_wallet                                          — check balance
2. clawallex_pay({ amount: 50, description: '...' })   — create card
3. get_card_details({ card_id: 'c_123' })              — get encrypted card data
4. decrypt_card_data({ encrypted_sensitive_data })      — decrypt PAN/CVV for checkout
5. list_transactions                                   — verify payment

Mode B Flow (x402 On-Chain, Two-Stage)

Stage 1 — Quote:
  clawallex_pay({
    amount: 200,
    description: 'GPU rental',
    mode_code: 200,
    chain_code: 'ETH',
    token_code: 'USDC'
  })
  → Returns 402 challenge:
    {
      client_request_id: "uuid-here",
      x402_reference_id: "x402_ref_001",
      payee_address: "0xsystem...",
      payable_amount: "207.5900",
      fee_amount: "7.5900",
      ...
    }

Agent signs — construct EIP-3009 transferWithAuthorization with your private key.

Stage 2 — Settle (use SAME client_request_id):
  clawallex_pay({
    amount: 200,
    description: 'GPU rental',
    mode_code: 200,
    client_request_id: 'uuid-here',         ← from Stage 1
    x402_version: 1,
    payment_payload: {
      scheme: 'exact',
      network: 'ETH',
      payload: {
        signature: '0x<EIP-3009 signature>',
        authorization: {
          from: '0x<your wallet>',
          to: '0xsystem...',               ← payee_address from Stage 1
          value: '207590000',              ← payable_amount × 10^6
          validAfter: '<unix seconds>',
          validBefore: '<unix seconds>',
          nonce: '0x<random 32-byte hex>'
        }
      }
    },
    payment_requirements: {
      scheme: 'exact',
      network: 'ETH',
      asset: '0x<asset_address>',          ← from Stage 1
      payTo: '0xsystem...',               ← payee_address from Stage 1
      maxAmountRequired: '207590000',      ← payable_amount × 10^6
      extra: {
        referenceId: 'x402_ref_001'        ← from Stage 1
      }
    },
    extra: {
      card_amount: '200.0000',             ← must equal amount
      paid_amount: '207.5900'              ← must equal payable_amount
    }
  })
  → Returns { card_order_id, card_id, status: 200 }

CRITICAL: Stage 2 client_request_id MUST be identical to Stage 1. A different value creates a new order instead of settling the existing one.

Client ID & Data Isolation

client_id is the agent's stable identity, separate from the API Key.

• An agent can have multiple API Keys (for rotation/revocation), but client_id never changes
• When switching to a new API Key, keep using the same client_id — the new key auto-binds on first request
• Once bound, it cannot be changed (TOFU — Trust On First Use)
• Stored locally at ~/.openclaw/clawallex/client_ids.json, keyed by baseUrl

Data isolation:

• Wallet — user-level, shared across all agents under the same API Key
• Cards & Transactions — scoped to client_id; each agent only sees its own

Use clawallex_whoami to check current binding status at any time.

Security: decrypt_card_data returns plaintext PAN/CVV for checkout use only. Agents must NEVER display these values to the user.

Smoke Test

After installing and configuring (clawallex_setup), verify with these 2 commands:

1. get_wallet      — should return wallet balance
2. list_cards      — should return card list (empty if no cards created)

Development

No build step required — OpenClaw runs .ts files natively.

npm install          # install type dependencies