Authentication
Include your API key in every request as a Bearer token. Generate a key using the POST /keys endpoint — no account required.
Authorization: Bearer sk_live_your_key_here
Keys are hashed on our end and cannot be recovered. Store your key securely, you will only see it once when it's generated.
POST /keys
POSTGenerate a new API key. No authentication required. Rate limited to 1 key per IP per hour.
curl -X POST https://api.clawd.cards/v1/keys
Response:
{
"api_key": "sk_live_a1b2c3d4e5f6g7h8i9j0...",
"created_at": "2026-02-16T14:00:00Z",
"message": "Store this key securely. It will not be shown again."
}
DELETE /keys
DELETERevoke your own API key. Requires authentication with the key being revoked. This action is permanent and immediate.
curl -X DELETE https://api.clawd.cards/v1/keys \
-H "Authorization: Bearer sk_live_..."
Response:
{
"revoked": true,
"message": "API key has been permanently revoked."
}
POST /cards
POSTRequest a virtual card for a purchase. Card details are returned once and cannot be retrieved again.
curl -X POST https://api.clawd.cards/v1/cards \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"amount": 1.00,
"merchant_category": "web_hosting",
"ttl_minutes": 1440
}'
Response:
{
"card": {
"number": "4111111111111111",
"cvv": "123",
"expiry": "12/26",
"spending_limit": 100,
"expires_at": "2026-02-17T14:00:00Z"
},
"transaction_id": "txn_abc123"
}
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| amount | number | Yes | Dollar amount for the card. Max $100 (production). Beta: max $1.00; requests above $1.00 will be rejected. |
| merchant_category | string | Yes | One of: web_hosting, cloud_compute, api_services, saas_tools, domains, databases, other |
| ttl_minutes | integer | No | Minutes until the card auto deletes. Min: 1, Max: 1440. Default: 1440 (24 hours). Card is permanently deleted after expiry. |
Card auto-deletes after the TTL expires or after first use, whichever comes first. Card details are returned only on this response — they cannot be retrieved again through any endpoint.
GET /limits
GETSee your real time spending capacity. All amounts in cents.
curl https://api.clawd.cards/v1/limits \
-H "Authorization: Bearer sk_live_..."
Response:
{
"monthly_limit": 50000,
"monthly_spent": 12000,
"monthly_remaining": 38000,
"per_transaction_limit": 10000,
"cards_remaining": 87
}
Fields:
monthly_limit- Your total monthly spending limit in cents. 50000 = $500.00monthly_spent- Amount spent so far this month in cents.monthly_remaining- Amount you can still spend this month in cents.per_transaction_limit- Maximum per card amount in cents. 10000 = $100.00. Beta: 100 = $1.00cards_remaining- Number of cards still available in the pool.
All values reflect real time availability. During beta, limits reflect the actual card pool and $1.00 per transaction cap.
Errors
All errors return a JSON body with a code and human-readable message.
{
"error": {
"code": "amount_exceeded",
"message": "Amount exceeds current per-transaction limit of $1.00 (beta)."
}
}
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_params | Missing or invalid parameters (bad amount, unknown category, invalid TTL). |
| 400 | amount_exceeded | Requested amount exceeds the per transaction limit. Beta: max $1.00. |
| 401 | invalid_key | API key is missing, malformed, or has been revoked. |
| 403 | limit_exceeded | Monthly spending limit reached. |
| 429 | rate_limited | Too many requests. Limit: 1 request per minute per key. |
| 429 | key_rate_limited | Key generation rate limit. 1 key per IP per hour. |
| 503 | no_cards_available | Card pool is exhausted. No cards currently available. |
Quick Start Examples
Generate an API Key
curl:
curl -X POST https://api.clawd.cards/v1/keys
# Save the returned key — you won't see it again
Node.js:
const res = await fetch('https://api.clawd.cards/v1/keys', {
method: 'POST'
});
const { api_key } = await res.json();
console.log('Save this key:', api_key);
Python:
import requests
response = requests.post('https://api.clawd.cards/v1/keys')
api_key = response.json()['api_key']
print(f'Save this key: {api_key}')
Create a Card
curl:
curl -X POST https://api.clawd.cards/v1/cards \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"amount": 1.00,
"merchant_category": "cloud_compute",
"ttl_minutes": 60
}'
Node.js:
const response = await fetch('https://api.clawd.cards/v1/cards', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.CLAWDCARDS_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
amount: 1.00,
merchant_category: 'cloud_compute',
ttl_minutes: 60
})
});
const { card, transaction_id } = await response.json();
console.log(`Card: ${card.number} | CVV: ${card.cvv} | Exp: ${card.expiry}`);
Python:
import requests
import os
response = requests.post(
'https://api.clawd.cards/v1/cards',
headers={'Authorization': f'Bearer {os.getenv("CLAWDCARDS_API_KEY")}'},
json={
'amount': 1.00,
'merchant_category': 'cloud_compute',
'ttl_minutes': 60
}
)
card = response.json()['card']
print(f"Card: {card['number']} | CVV: {card['cvv']} | Exp: {card['expiry']}")
Full Workflow
Node.js:
// 1. Check your limits
const limits = await fetch('https://api.clawd.cards/v1/limits', {
headers: { 'Authorization': `Bearer ${API_KEY}` }
}).then(r => r.json());
if (limits.cards_remaining === 0) {
console.log('No cards available');
process.exit(1);
}
// 2. Create a card
const { card } = await fetch('https://api.clawd.cards/v1/cards', {
method: 'POST',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
amount: 1.00,
merchant_category: 'web_hosting',
ttl_minutes: 1440
})
}).then(r => r.json());
// 3. Use the card (your purchase logic here)
console.log(`Use card ${card.number} before ${card.expires_at}`);
// 4. Review your history
const { transactions } = await fetch('https://api.clawd.cards/v1/transactions', {
headers: { 'Authorization': `Bearer ${API_KEY}` }
}).then(r => r.json());
Python:
import requests, os
API_KEY = os.getenv("CLAWDCARDS_API_KEY")
headers = {'Authorization': f'Bearer {API_KEY}'}
# 1. Check your limits
limits = requests.get(
'https://api.clawd.cards/v1/limits',
headers=headers
).json()
if limits['cards_remaining'] == 0:
print('No cards available')
exit(1)
# 2. Create a card
card_res = requests.post(
'https://api.clawd.cards/v1/cards',
headers=headers,
json={
'amount': 1.00,
'merchant_category': 'web_hosting',
'ttl_minutes': 1440
}
).json()
card = card_res['card']
# 3. Use the card (your purchase logic here)
print(f"Use card {card['number']} before {card['expires_at']}")
# 4. Review your history
txns = requests.get(
'https://api.clawd.cards/v1/transactions',
headers=headers
).json()
Security Best Practices
ClawdCards issues real virtual card numbers. Treat all card data with the same care as your own credit card.
- Never log card numbers. Card details (number, CVV, expiry) should never be written to logs, console output, or monitoring tools. Use the
card_last_fourfrom the transactions endpoint for reference. - Use environment variables for your API key. Never hardcode your key in source code, commit it to version control, or expose it in client side code.
- Card details are returned once. The
POST /cardsresponse is the only time you will see full card details. Store them securely in memory for immediate use, do not persist them to disk or database. - HTTPS only. All API requests must use HTTPS. HTTP requests will be rejected.
- Revoke compromised keys immediately. If your API key is exposed, revoke it with
DELETE /keysand generate a new one. - Respect card TTL. Cards auto-delete after their configured TTL (default 24 hours) or after first use. Do not attempt to reuse expired cards.
- Agent integration. If giving card access to an AI agent, scope the agent's permissions so it can only request cards for approved merchant categories and amounts.