🦞 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

1Create an API key

# Your key looks like:
ak_live_dG9rZW4tZXhhbXBsZS1iYXNlNjR1cmw...

2Get your key details

Your key comes with an auto-provisioned email and phone number. Fetch the details:

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

# Response:
[{
  "id": "agt_abc123",
  "name": "my-agent",
  "email": "inbox-7xk@mail.clawcard.sh",
  "phone": "+12025551234",
  "cardsEnabled": true,
  "spendLimitCents": 0,
  "status": "active"
}]

3Use it

Read emails, send SMS, create virtual cards — all via simple REST calls.

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

# Response:
{
  "id": "card_xyz",
  "pan": "5412753400124242",
  "cvv": "321",
  "exp_month": 12,
  "exp_year": 2029,
  "spendLimitCents": 2000,
  "status": "open"
}

OpenClaw Integration

Using OpenClaw? Copy the ClawCard skill from the setup page in your dashboard. Your agent will automatically discover all endpoints via the skill definition.

Authentication

All API requests require a Bearer token in the Authorization header. Use the API key generated when you created your key in the dashboard.

Authorization: Bearer ak_live_dG9rZW4tZXhhbXBsZS1iYXNlNjR1cmw...

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_dG9rZW4t",
    "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": "ak_live_dG9rZW4tZXhhbXBsZS1iYXNlNjR1cmw...",
  "keyPrefix": "ak_live_dG9rZW4t",
  "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_dG9rZW4t",
  "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`	string	"single_use" or "merchant_locked" (default: "single_use")
`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,"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.

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.

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 your balance from the dashboard settings page.

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:closecreds: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)