🦞 Documentation

ClawCard API

Give your AI agent a full identity — email inbox, phone number, virtual credit card, and encrypted credential vault. One API key, simple REST endpoints.

Email

Send & receive emails from a dedicated inbox

SMS

Send & receive text messages with a real US number

Virtual Cards

Issue Mastercards with per-card spend limits

Quickstart

1Install & sign up

Install the ClawCard CLI and create an account.

npm install -g @clawcard/cli

# Sign up (requires invite code)
clawcard signup

# Top up your balance (minimum $5)
clawcard billing topup

2Create your agent & configure

Create an agent key, then run setup to install the ClawCard skill. Works with Claude Code, Cursor, Codex, OpenClaw, and 40+ other agents.

# Create your agent (gets email, phone, cards)
clawcard keys create

# Install skill for your agent harness
clawcard setup

3Your agent uses CLI commands

Your agent runs clawcard agent commands directly. The API key stays hidden — your agent never sees it.

# Agent checks its identity
clawcard agent info --json

# Agent sends an email
clawcard agent emails send --to "user@example.com" --subject "Hello" --body "Hi" --json

# Agent creates a virtual card
clawcard agent cards create --amount 2000 --type single_use --memo "Domain" --json

# Agent stores a credential
clawcard agent creds set --service openai --key api_key --value "sk-..." --json

How it works

clawcard setup uses skills.sh to install a skill file that teaches your agent all available CLI commands. The API key is stored in ~/.clawcard/.env and used internally by the CLI — your agent never touches it directly.

CLI Reference

Your agent interacts with ClawCard through CLI commands. All agent commands support --json for machine-readable output.

Agent Commands

These are the commands your agent runs. Always pass --json.

Command	Description
`clawcard agent info`	Agent identity (email, phone, budget)
`clawcard agent emails`	List inbox (--limit, --unread)
`clawcard agent emails send --to --subject --body`	Send email
`clawcard agent emails read <id>`	Mark email as read
`clawcard agent sms`	List SMS messages (--limit)
`clawcard agent sms send --to --body`	Send SMS
`clawcard agent cards`	List virtual cards
`clawcard agent cards create --amount --type --memo`	Create card (amount in cents)
`clawcard agent cards details <id>`	Get PAN, CVV, expiry
`clawcard agent cards close <id>`	Close card permanently
`clawcard agent cards pause <id>`	Pause card
`clawcard agent cards resume <id>`	Resume card
`clawcard agent wallet`	Show wallet address & balances
`clawcard agent wallet fund`	Fund wizard (ETH, USDC, or pathUSD)
`clawcard agent wallet balance`	Check USDC, ETH, pathUSD balances
`clawcard agent wallet send --to --amount`	Send USDC to an address
`clawcard agent wallet send --url`	Pay x402/MPP API (--protocol mpp)
`clawcard agent wallet transactions`	Transaction history
`clawcard agent wallet freeze`	Freeze wallet (blocks sends)
`clawcard agent wallet unfreeze`	Unfreeze wallet
`clawcard agent wallet close`	Close wallet permanently
`clawcard agent creds`	List stored credentials
`clawcard agent creds set --service --key --value`	Store credential
`clawcard agent creds get --service --key`	Retrieve credential
`clawcard agent budget`	Check remaining budget
`clawcard agent activity`	View activity log (--limit)

User Commands

These are for you, the human, to manage your account.

Command	Description
`clawcard signup`	Sign up with invite code
`clawcard login`	Log in via browser
`clawcard logout`	Clear session
`clawcard billing topup`	Top up balance
`clawcard billing balance`	Check balance
`clawcard keys create`	Create agent key
`clawcard keys revoke`	Revoke key (exports credentials)
`clawcard setup`	Install skill for your agent
`clawcard agent`	View agent details
`clawcard agent fund`	Allocate card budget to agent
`clawcard agent wallet fund`	Fund wallet (ETH/USDC/pathUSD)
`clawcard referral`	Show referral code
`clawcard help`	Show all commands

Card types

When creating cards, --type is required. Use single_use for one-time purchases (auto-closes after one charge) or merchant_locked for subscriptions (locks to first merchant, allows repeat charges). Always list existing cards before creating new ones — reuse open merchant-locked cards to save budget.

Credential naming convention

Use consistent lowercase naming so credentials are easy to find later:

# --service: lowercase service name
# --key: lowercase key type

clawcard agent creds set --service openai --key api_key --value "sk-..." --json
clawcard agent creds set --service vercel --key access_token --value "..." --json
clawcard agent creds set --service aws --key secret_key --value "..." --json

Authentication

Your agent uses clawcard agent CLI commands which handle authentication automatically. For direct API access, all requests require a Bearer token in the Authorization header.

Authorization: Bearer <YOUR_API_KEY>

Key format

•Prefix: ak_live_ followed by 32 random bytes (base64url encoded)
•The raw key is shown only once at creation. Store it securely.
•The dashboard shows a truncated prefix for identification.

All endpoints return 401 Unauthorized if the key is missing, invalid, or revoked.

API Keys

Create, list, update, and delete API keys. Each key gets an auto-provisioned email inbox and phone number.

GET/api/agents

List all API keys for the authenticated user.

Example

curl -H "Authorization: Bearer $CLAWCARD_API_KEY" \
  https://clawcard.sh/api/agents

Response

[
  {
    "id": "agt_abc123",
    "name": "my-agent",
    "keyPrefix": "ak_live_...",
    "email": "inbox-7xk@mail.clawcard.sh",
    "phone": "+12025551234",
    "cardsEnabled": true,
    "spendLimitCents": 5000,
    "status": "active",
    "createdAt": "2026-03-08T12:00:00.000Z"
  }
]

POST/api/agents

Create a new API key. Returns the raw key once — store it securely.

Request Body

Field	Type	Description
`name`	string	Friendly name (default: "default")

Example

curl -X POST \
  -H "Authorization: Bearer $CLAWCARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent"}' \
  https://clawcard.sh/api/agents

Response

{
  "id": "agt_newkey123",
  "name": "my-agent",
  "apiKey": "<YOUR_API_KEY>",
  "keyPrefix": "ak_live_...",
  "email": "inbox-9ab@mail.clawcard.sh",
  "phone": "+12025559876",
  "cardsEnabled": true,
  "spendLimitCents": 0,
  "status": "active",
  "createdAt": "2026-03-08T12:00:00.000Z"
}

The apiKey field is only returned on creation. Store it immediately.

GET/api/agents/{id}

Get details for a specific API key.

Example

curl -H "Authorization: Bearer $CLAWCARD_API_KEY" \
  https://clawcard.sh/api/agents/agt_abc123

Response

{
  "id": "agt_abc123",
  "name": "my-agent",
  "keyPrefix": "ak_live_...",
  "email": "inbox-7xk@mail.clawcard.sh",
  "phone": "+12025551234",
  "cardsEnabled": true,
  "spendLimitCents": 5000,
  "status": "active",
  "createdAt": "2026-03-08T12:00:00.000Z",
  "updatedAt": "2026-03-08T14:30:00.000Z"
}

PATCH/api/agents/{id}

Update API key properties.

Request Body

Field	Type	Description
`name`	string	New friendly name
`cardsEnabled`	boolean	Enable or disable card creation (emergency kill switch)

Example

curl -X PATCH \
  -H "Authorization: Bearer $CLAWCARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cardsEnabled": false}' \
  https://clawcard.sh/api/agents/agt_abc123

Response

{ "success": true }

DELETE/api/agents/{id}

Delete an API key and all associated resources. Closes all cards and refunds remaining budget.

Example

curl -X DELETE \
  -H "Authorization: Bearer $CLAWCARD_API_KEY" \
  https://clawcard.sh/api/agents/agt_abc123

Response

{ "success": true }

This action is irreversible. All cards are closed, credentials deleted, and remaining budget refunded to your account balance.

Email

Each key gets a dedicated email inbox. Send and receive emails programmatically.

GET/api/agents/{id}/emails

List emails in the inbox. Supports filtering by read status, sender, and subject.

Query Parameters

unreadboolean— Filter to unread only (pass "true")

fromstring— Filter by sender email address

subject_containsstring— Search subject line

limitnumber— Max results, 1-100 (default: 20)

Example

curl -H "Authorization: Bearer $CLAWCARD_API_KEY" \
  "https://clawcard.sh/api/agents/agt_abc123/emails?unread=true&limit=10"

Response

[
  {
    "id": "em_abc123",
    "sender": "support@example.com",
    "recipient": "inbox-7xk@mail.clawcard.sh",
    "subject": "Welcome!",
    "body": "Thanks for signing up...",
    "html": "<p>Thanks for signing up...</p>",
    "isRead": false,
    "direction": "inbound",
    "createdAt": "2026-03-08T12:00:00.000Z"
  }
]

POST/api/agents/{id}/emails/send

Send an email from the key's email address.

Request Body

Field	Type	Description
`to`required	string	Recipient email address
`subject`required	string	Email subject line
`body`required	string	Email body (plain text or HTML)

Example

curl -X POST \
  -H "Authorization: Bearer $CLAWCARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"user@example.com","subject":"Hello","body":"Hi there!"}' \
  https://clawcard.sh/api/agents/agt_abc123/emails/send

Response

{
  "id": "em_xyz789",
  "resendId": "re_abc...",
  "from": "inbox-7xk@mail.clawcard.sh",
  "to": "user@example.com",
  "subject": "Hello from my agent",
  "createdAt": "2026-03-08T12:00:00.000Z"
}

POST/api/agents/{id}/emails/{emailId}/read

Mark an email as read.

Example

curl -X POST \
  -H "Authorization: Bearer $CLAWCARD_API_KEY" \
  https://clawcard.sh/api/agents/agt_abc123/emails/em_abc123/read

Response

{
  "success": true,
  "id": "em_abc123",
  "isRead": true
}

SMS

Each key gets a US phone number. Send and receive SMS messages.

GET/api/agents/{id}/sms

List SMS messages sent and received.

Query Parameters

limitnumber— Max results, 1-200 (default: 50)

Example

curl -H "Authorization: Bearer $CLAWCARD_API_KEY" \
  https://clawcard.sh/api/agents/agt_abc123/sms

Response

[
  {
    "id": "sms_abc123",
    "from": "+12025551234",
    "to": "+15551234567",
    "body": "Your verification code is 123456",
    "direction": "inbound",
    "createdAt": "2026-03-08T12:00:00.000Z"
  }
]

POST/api/agents/{id}/sms/send

Send an SMS from the key's phone number.

Request Body

Field	Type	Description
`to`required	string	Recipient phone number (E.164 format)
`body`required	string	Message text

Example

curl -X POST \
  -H "Authorization: Bearer $CLAWCARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"+15551234567","body":"Hello from my agent!"}' \
  https://clawcard.sh/api/agents/agt_abc123/sms/send

Response

{
  "id": "sms_xyz789",
  "telnyxId": "tx_abc...",
  "from": "+12025551234",
  "to": "+15551234567",
  "body": "Hello from my agent!",
  "direction": "outbound",
  "createdAt": "2026-03-08T12:00:00.000Z"
}

Virtual Cards

Issue virtual Mastercards with per-card spend limits. Powered by Privacy.com.

GET/api/agents/{id}/cards

List all virtual cards for this key.

Example

curl -H "Authorization: Bearer $CLAWCARD_API_KEY" \
  https://clawcard.sh/api/agents/agt_abc123/cards

Response

{
  "cards": [
    {
      "id": "card_abc123",
      "lastFour": "4242",
      "type": "single_use",
      "memo": "Domain purchase",
      "spendLimitCents": 2000,
      "status": "open",
      "createdAt": "2026-03-08T12:00:00.000Z"
    }
  ]
}

POST/api/agents/{id}/cards

Create a new virtual card. Full card details (PAN, CVV, expiry) are returned only at creation.

Request Body

Field	Type	Description
`amountCents`required	number	Spending limit in cents (min: 100)
`type`required	string	"single_use" (auto-closes after one charge) or "merchant_locked" (reusable at same merchant)
`memo`	string	Card description (default: "Agent card")

Example

curl -X POST \
  -H "Authorization: Bearer $CLAWCARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amountCents":2000,"type":"single_use","memo":"Domain purchase"}' \
  https://clawcard.sh/api/agents/agt_abc123/cards

Response

{
  "id": "card_xyz789",
  "pan": "5412753400124242",
  "cvv": "321",
  "exp_month": 12,
  "exp_year": 2029,
  "lastFour": "4242",
  "type": "single_use",
  "memo": "Domain purchase",
  "spendLimitCents": 2000,
  "status": "open",
  "createdAt": "2026-03-08T12:00:00.000Z"
}

Requires sufficient budget allocated to the key and cardsEnabled: true. The type field is required.

GET/api/agents/{id}/cards/{cardId}

Get full card details including PAN and CVV.

Example

curl -H "Authorization: Bearer $CLAWCARD_API_KEY" \
  https://clawcard.sh/api/agents/agt_abc123/cards/card_abc123

Response

{
  "id": "card_abc123",
  "pan": "5412753400124242",
  "cvv": "321",
  "exp_month": 12,
  "exp_year": 2029,
  "lastFour": "4242",
  "type": "single_use",
  "memo": "Domain purchase",
  "spendLimitCents": 2000,
  "status": "open"
}

PATCH/api/agents/{id}/cards/{cardId}

Manage card status: pause, resume, or close permanently.

Request Body

Field	Type	Description
`action`required	string	"pause", "resume", or "close"

Example

curl -X PATCH \
  -H "Authorization: Bearer $CLAWCARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"pause"}' \
  https://clawcard.sh/api/agents/agt_abc123/cards/card_abc123

Response

{
  "success": true,
  "status": "paused"
}

Closing a card is permanent and cannot be undone.

Crypto Wallet

Multi-asset wallet on Base for paying APIs (x402/MPP), sending crypto, and receiving payments. Holds USDC (x402), ETH (gas), and pathUSD (MPP on Tempo). Gasless signing for x402 — direct transfers require a tiny bit of ETH for gas.

Setup

Create a wallet for your agent. Each agent gets one wallet — calling this again returns the existing one.

# Interactive (prompts to create if none exists)
$ clawcard agent wallet

# JSON mode (returns wallet or error)
$ clawcard agent wallet --json

Fund Your Wallet

Interactive wizard with three funding options: ETH (gas), USDC (x402 payments), and pathUSD (MPP payments). ETH and USDC are purchased via Coinbase Onramp. pathUSD is bridged from your existing USDC balance.

# Interactive wizard — choose what to fund
$ clawcard agent wallet fund

# Options:
#   1. Gas fees (ETH)       — Buy ETH via Coinbase ($1-2 covers thousands of txns)
#   2. x402 services (USDC) — Buy USDC via Coinbase (zero fees)
#   3. MPP services (pathUSD) — Bridge USDC → pathUSD on Tempo

# Or send USDC + ETH directly to your wallet address on Base
$ clawcard agent wallet --json  # shows your 0x address

Important: Your wallet needs both USDC (spending money) and a small amount of ETH (for gas fees). $1-2 of ETH covers thousands of transactions on Base. For MPP services, you also need pathUSD — the fund wizard handles the USDC-to-pathUSD bridge automatically.

Bridge USDC to pathUSD

MPP (Machine Payments Protocol) services use pathUSD on the Tempo network. The fund wizard can bridge your USDC to pathUSD, or you can call the bridge API directly.

# Via the fund wizard (choose "MPP services (pathUSD)")
$ clawcard agent wallet fund

# Response includes explorer links:
#   Base TX:  https://basescan.org/tx/0x...
#   Tempo:    https://explore.tempo.xyz/receipt/0x...

# Verify balance after bridge
$ clawcard agent wallet balance --json

Check Balance

Shows ETH (gas), USDC (x402), and pathUSD (MPP) balances.

$ clawcard agent wallet balance --json
{
  "balanceUsdc": "10.000000",
  "balanceEth": "0.001234",
  "balancePathUsd": "5.000000",
  "fiatBudgetCents": 700,
  "effectiveUsdc": "17.00"
}

POST/api/agents/:id/wallet

Create a multi-asset wallet on Base for the agent. Returns 409 if wallet already exists.

Example

curl -X POST https://clawcard.sh/api/agents/AGENT_ID/wallet \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{}'

Response

{
  "id": "awd_q5khwp12",
  "address": "0xC7d0...6D74",
  "network": "base",
  "balanceUsdc": "0.000000",
  "balanceEth": "0.000000",
  "balancePathUsd": "0.000000",
  "status": "active",
  "createdAt": "2026-03-21T08:31:16.966Z"
}

GET/api/agents/:id/wallet

Get wallet details including USDC, ETH, and pathUSD balances. Syncs balance from chain every 30 seconds.

Example

curl https://clawcard.sh/api/agents/AGENT_ID/wallet \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "id": "awd_q5khwp12",
  "address": "0xC7d0...6D74",
  "network": "base",
  "balanceUsdc": "10.000000",
  "balanceEth": "0.001234",
  "balancePathUsd": "5.000000",
  "status": "active",
  "createdAt": "2026-03-21T08:31:16.966Z"
}

Send USDC

Send USDC to any address on Base. Requires ETH in wallet for gas.

$ clawcard agent wallet send --to 0xADDRESS --amount 5.00 --json
{
  "success": true,
  "txId": "wtx_abc12345",
  "txHash": "0xaf89cf...",
  "amountUsdc": "5.000000",
  "to": "0xADDRESS",
  "protocol": "direct"
}

Pay an x402 API

Pay for any x402-enabled API. The wallet signs the payment, the facilitator settles on-chain, and you get the API response back. Cost is determined by the API (typically fractions of a cent).

$ clawcard agent wallet send --url "https://x402.twit.sh/tweets/search?words=AI+agents" --json
{
  "success": true,
  "protocol": "x402",
  "txHash": "0xb80b05...",
  "url": "https://x402.twit.sh/tweets/search?words=AI+agents",
  "amountUsdc": "0.010000",
  "data": "{ ... tweet data ... }"
}

Pay an MPP API

Machine Payments Protocol (Stripe/Tempo). Uses pathUSD on the Tempo network. Fund your wallet with pathUSD first via the fund wizard.

$ clawcard agent wallet send --url "https://api.example.com/data" --protocol mpp --json
{
  "success": true,
  "protocol": "mpp",
  "txHash": "0x9c3e...",
  "url": "https://api.example.com/data",
  "amountUsdc": "0.050000",
  "explorerUrl": "https://explore.tempo.xyz/receipt/0x9c3e...",
  "data": "{ ... response data ... }"
}

MPP transactions link to the Tempo explorer instead of Basescan.

POST Requests with Body

For APIs that require POST with a JSON body, use --method and --body flags.

$ clawcard agent wallet send \
  --url "https://api.example.com/submit" \
  --method POST \
  --body '{"query":"AI agents"}' \
  --json

POST/api/agents/:id/wallet/send

Send USDC directly or pay an x402/MPP URL. For MPP, payment is in pathUSD on Tempo.

Request Body

Field	Type	Description
`to`	string	Recipient 0x address (for direct send)
`amountUsdc`	string	Amount in USDC, e.g. '5.00' (for direct send)
`url`	string	x402/MPP URL to pay (for API payments)
`protocol`	string	Payment protocol: 'x402' (default) or 'mpp'
`method`	string	HTTP method for URL payments: 'GET' (default) or 'POST'
`body`	object	JSON request body (for POST URL payments)
`memo`	string	Optional transaction memo

Example

curl -X POST https://clawcard.sh/api/agents/AGENT_ID/wallet/send \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{"to": "0xADDRESS", "amountUsdc": "5.00"}'

Response

{
  "success": true,
  "txHash": "0xaf89cf...",
  "amountUsdc": "5.000000",
  "to": "0xADDRESS",
  "protocol": "direct"
}

Transaction History

$ clawcard agent wallet transactions --json
{
  "transactions": [
    {
      "id": "wtx_abc12345",
      "type": "send",
      "amountUsdc": "0.010000",
      "counterparty": "https://x402.twit.sh/...",
      "txHash": "0xb80b05...",
      "protocol": "x402",
      "status": "confirmed",
      "createdAt": "2026-03-21T..."
    },
    {
      "id": "wtx_def67890",
      "type": "send",
      "amountUsdc": "0.050000",
      "counterparty": "https://api.example.com/...",
      "txHash": "0x9c3e...",
      "protocol": "mpp",
      "status": "confirmed",
      "createdAt": "2026-03-21T..."
    },
    {
      "id": "wtx_ghi11111",
      "type": "bridge",
      "amountUsdc": "5.000000",
      "counterparty": "USDC→pathUSD",
      "txHash": "0xaf89...",
      "protocol": "bridge",
      "status": "confirmed",
      "createdAt": "2026-03-21T..."
    }
  ]
}

x402/direct transactions link to basescan.org. MPP and bridge transactions link to the Tempo explorer.

Freeze / Close Wallet

# Freeze — blocks all sends
$ clawcard agent wallet freeze --json

# Unfreeze
$ clawcard agent wallet unfreeze --json

# Close permanently
$ clawcard agent wallet close --json

Service Discovery

Discover x402-enabled APIs from the Coinbase Bazaar. 13,000+ services — web search, data enrichment, AI models, and more. Pay per request with your wallet.

Browse Services

# Browse all available services
$ clawcard agent discover --json

# Search for specific capabilities
$ clawcard agent discover --query "tweet" --json
$ clawcard agent discover --query "search" --json
$ clawcard agent discover --query "weather" --json

GET/api/discover

Discover x402-enabled services from the Coinbase Bazaar. Public endpoint — no auth required.

Query Parameters

qstring— Search term to filter by URL

limitnumber— Max results (default 20, max 100)

offsetnumber— Pagination offset

Example

curl "https://clawcard.sh/api/discover?q=search&limit=5"

Response

{
  "services": [
    {
      "url": "https://x402.twit.sh/tweets/search",
      "description": "https://x402.twit.sh/tweets/search",
      "network": "eip155:8453",
      "priceUsdc": "0.010000",
      "payTo": "0x9DBA..."
    }
  ],
  "total": 13029
}

Use a Discovered Service

Once you find a service, pay for it with your wallet:

# 1. Discover
$ clawcard agent discover --query "tweet" --json

# 2. Pay and get data
$ clawcard agent wallet send --url "https://x402.twit.sh/tweets/search?words=bitcoin" --json

On-Chain Identity

ERC-8004 identity on Base — a verifiable, portable NFT that proves who your agent is. Other agents and services can look up your agent on-chain.

# Register or view on-chain identity
$ clawcard agent identity --json

# View your A2A agent card (discovery document)
$ clawcard agent card --json

POST/api/agents/:id/identity

Register an ERC-8004 on-chain identity for the agent. Builds metadata from agent profile (name, email, wallet, capabilities) and returns transaction data for on-chain submission.

Request Body

Field	Type	Description
`capabilities`	string[]	Optional list of capabilities (auto-detected if omitted)

Example

curl -X POST https://clawcard.sh/api/agents/AGENT_ID/identity \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{}'

Response

{
  "walletAddress": "0xC7d0...6D74",
  "network": "base",
  "metadata": {
    "name": "cb-agent",
    "properties": {
      "walletAddress": "0xC7d0...6D74",
      "email": "cb-agent-7qig@clawcard.sh",
      "capabilities": ["email", "sms", "virtual-cards", "wallet", "credentials"]
    }
  },
  "registryAddress": "0x8004A169..."
}

GET/api/agents/:id/agent-card

Get the A2A agent card — a public discovery document that describes what your agent can do. Other agents use this to find and interact with yours. No auth required.

Example

curl https://clawcard.sh/api/agents/AGENT_ID/agent-card

Response

{
  "name": "cb-agent",
  "description": "ClawCard agent: cb-agent",
  "version": "1.0.0",
  "provider": { "organization": "ClawCard" },
  "skills": [
    { "name": "email", "description": "Send and receive email" },
    { "name": "wallet", "description": "Send and receive USDC on Base" }
  ]
}

This is a public endpoint — no authentication required. Used for agent-to-agent discovery.

Credentials

Encrypted key-value vault for storing API keys and secrets your agent needs at runtime.

GET/api/agents/{id}/credentials

List stored credentials (names only, values not returned).

Example

curl -H "Authorization: Bearer $CLAWCARD_API_KEY" \
  https://clawcard.sh/api/agents/agt_abc123/credentials

Response

[
  { "service": "openai", "key": "api_key" },
  { "service": "stripe", "key": "secret_key" }
]

POST/api/agents/{id}/credentials

Store or update an encrypted credential.

Request Body

Field	Type	Description
`service`required	string	Service name (e.g. "openai")
`key`required	string	Credential key (e.g. "api_key")
`value`required	string	Secret value (encrypted at rest)

Example

curl -X POST \
  -H "Authorization: Bearer $CLAWCARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service":"openai","key":"api_key","value":"sk-..."}' \
  https://clawcard.sh/api/agents/agt_abc123/credentials

Response

{
  "success": true,
  "service": "openai",
  "key": "api_key"
}

GET/api/agents/{id}/credentials/{service}/{key}

Retrieve a decrypted credential value.

Example

curl -H "Authorization: Bearer $CLAWCARD_API_KEY" \
  https://clawcard.sh/api/agents/agt_abc123/credentials/openai/api_key

Response

{
  "service": "openai",
  "key": "api_key",
  "value": "sk-..."
}

Budget

Allocate funds from your account balance to a key's spending budget. Budget controls how much the key can spend on virtual cards.

GET/api/agents/{id}/budget

Get the current budget for this key.

Example

curl -H "Authorization: Bearer $CLAWCARD_API_KEY" \
  https://clawcard.sh/api/agents/agt_abc123/budget

Response

{ "budgetCents": 5000 }

POST/api/agents/{id}/budget

Allocate funds from your account balance to this key's budget.

Request Body

Field	Type	Description
`amountCents`required	number	Amount to allocate in cents (min: 100)

Example

curl -X POST \
  -H "Authorization: Bearer $CLAWCARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amountCents": 2000}' \
  https://clawcard.sh/api/agents/agt_abc123/budget

Response

{
  "success": true,
  "balanceRemainingCents": 8000,
  "agentBudgetCents": 7000
}

Requires sufficient account balance. Top up via clawcard billing topup or from the dashboard.

Activity Log

Full audit trail of every action performed by or for this key.

GET/api/agents/{id}/activity

List recent activity for this key.

Query Parameters

limitnumber— Max results (default: 50)

Example

curl -H "Authorization: Bearer $CLAWCARD_API_KEY" \
  https://clawcard.sh/api/agents/agt_abc123/activity

Response

{
  "activity": [
    {
      "id": "act_abc123",
      "action": "card:create",
      "details": "{"memo":"Domain purchase","amountCents":2000}",
      "createdAt": "2026-03-08T12:00:00.000Z"
    },
    {
      "id": "act_def456",
      "action": "email:send",
      "details": "{"to":"user@example.com","subject":"Hello"}",
      "createdAt": "2026-03-08T11:55:00.000Z"
    }
  ]
}

Action types

email:receiveemail:sendsms:receivesms:sendcard:createcard:readcard:pausecard:resumecard:closewallet:sendwallet:x402wallet:mppwallet:bridgecreds:write

Base URL

All API requests should be made to:

https://clawcard.sh

All endpoints are prefixed with /api. Example: https://clawcard.sh/api/agents

Error Responses

All errors return a JSON object with an error field:

{
  "error": "Insufficient budget"
}

# Common HTTP status codes:
# 400 - Bad request (missing/invalid fields)
# 401 - Unauthorized (bad or missing API key)
# 403 - Forbidden (e.g. cards disabled)
# 404 - Not found
# 503 - Service unavailable (external dependency down)