Let your agent shop online with guardrailed wallets, multiple payment methods, and owner approval.
CreditClaw lets your agent buy things online — Amazon products, Shopify stores, SaaS subscriptions, and more. Your owner funds a wallet, sets spending limits, and you shop within those guardrails.
| File | URL | Purpose |
|---|---|---|
| SKILL.md (this file) | https://creditclaw.com/creditcard/skill.md | Registration, setup, payment method guide, and API reference |
| SHOPPING.md | https://creditclaw.com/creditcard/shopping.md | General purchasing guide — merchant types, tips, common patterns |
| AMAZON.md | https://creditclaw.com/creditcard/amazon.md | Amazon-specific guide — ASIN discovery, restrictions, tracking |
| PREPAID-WALLET.md | https://creditclaw.com/creditcard/prepaid-wallet.md |
| Pre-paid Wallet (Rail 2) — purchase flow, merchant formats, order tracking |
| SELF-HOSTED-CARD.md | https://creditclaw.com/creditcard/self-hosted-card.md | Self-Hosted Card (Rail 4) — checkout flow, approval, multi-card handling |
| STRIPE-X402-WALLET.md | https://creditclaw.com/creditcard/stripe-x402-wallet.md | Stripe x402 Wallet (Rail 1) — x402 signing, USDC balance, guardrails |
| HEARTBEAT.md | https://creditclaw.com/creditcard/heartbeat.md | Lightweight polling routine for balance and spending checks |
| package.json (metadata) | https://creditclaw.com/creditcard/skill.json | Machine-readable skill metadata |
Follow your human's instructions on how to manage and save skill files. If unsure, you can install locally:
mkdir -p ~/.creditclaw/skills/creditcard
curl -s https://creditclaw.com/creditcard/skill.md > ~/.creditclaw/skills/creditcard/SKILL.md
curl -s https://creditclaw.com/creditcard/shopping.md > ~/.creditclaw/skills/creditcard/SHOPPING.md
curl -s https://creditclaw.com/creditcard/amazon.md > ~/.creditclaw/skills/creditcard/AMAZON.md
curl -s https://creditclaw.com/creditcard/prepaid-wallet.md > ~/.creditclaw/skills/creditcard/PREPAID-WALLET.md
curl -s https://creditclaw.com/creditcard/self-hosted-card.md > ~/.creditclaw/skills/creditcard/SELF-HOSTED-CARD.md
curl -s https://creditclaw.com/creditcard/stripe-x402-wallet.md > ~/.creditclaw/skills/creditcard/STRIPE-X402-WALLET.md
curl -s https://creditclaw.com/creditcard/heartbeat.md > ~/.creditclaw/skills/creditcard/HEARTBEAT.md
curl -s https://creditclaw.com/creditcard/skill.json > ~/.creditclaw/skills/creditcard/package.json
Or just read them directly from the URLs above.
Base URL: https://creditclaw.com/api/v1
CreditClaw supports multiple payment methods. Your owner chooses which ones to enable for you.
| Payment Method | Best For | Status | Day-to-Day Guide |
|---|---|---|---|
| Pre-paid Wallet | Amazon, Shopify, supported merchants | Live | prepaid-wallet.md |
| Self-Hosted Card | SaaS, cloud hosting, any online store | Live | self-hosted-card.md |
| Stripe x402 Wallet | x402 services, agent-to-agent payments | Private Beta | stripe-x402-wallet.md |
Check GET /bot/status to see your full status across all connected rails, or use the per-rail check endpoints below.
| I need to... | Use | Why |
|---|---|---|
| Buy something on Amazon | Pre-paid Wallet | Full order tracking, ASIN-based purchasing |
| Buy from a Shopify store | Pre-paid Wallet | Variant lookup + direct ordering |
| Pay for a SaaS subscription | Self-Hosted Card | Works with any merchant that accepts cards |
| Pay for cloud hosting (AWS, DigitalOcean, etc.) | Self-Hosted Card | Works with any merchant that accepts cards |
| Buy from any online store | Self-Hosted Card | Works with any merchant URL |
| Pay an x402-enabled API or service | Stripe x402 Wallet | On-chain USDC settlement via x402 protocol |
| Send payment to another agent | Stripe x402 Wallet | Agent-to-agent via x402 |
For general shopping advice and tips, see shopping.md.
For Amazon-specific details (ASIN discovery, restrictions, tracking), see amazon.md.
Default safety: New accounts require human approval for every purchase (approval_mode: ask_for_everything). Your owner can adjust this from their dashboard once they're comfortable with your spending patterns.
All requests require: Authorization: Bearer <your-api-key> (except registration).
🔒 CRITICAL SECURITY WARNING:
creditclaw.comhttps://creditclaw.com/api/*CreditClaw is designed with defense-in-depth to protect your owner's funds:
approval_mode, spending limits, category blocks, and domain restrictions are checked by CreditClaw's servers before any funds move — regardless of what happens on the client side. There is no way to bypass these controls.1. You fetch this skill file from creditclaw.com/creditcard/skill.md
2. You call POST /bots/register → get apiKey + claimToken
3. You tell your human the claimToken and verification link
4. Human visits creditclaw.com/claim, enters claimToken, adds payment method
5. Your wallet activates
6. You poll GET /bot/status periodically to monitor balance across all rails
7. You check GET /bot/wallet/spending for your owner's permission rules
8. You spend via the rail your owner has enabled for you
9. When balance is low, you request a top-up or generate a payment link
10. Human monitors activity from creditclaw.com/app
Alternative flow (owner-first): If your human already has a CreditClaw account, they can
generate a 6-digit pairing code from their dashboard. Include it as pairing_code during
registration and your wallet activates instantly — no claim step needed.
Register to get your API key and a claim token for your human.
curl -X POST https://creditclaw.com/api/v1/bots/register \
-H "Content-Type: application/json" \
-d '{
"bot_name": "my-research-bot",
"owner_email": "[email protected]",
"description": "Performs web research tasks for hire",
"callback_url": "https://my-bot.example.com/webhook"
}'
Request fields:
| Field | Required | Description |
|---|---|---|
bot_name | Yes | Your bot's name (1-100 chars) |
owner_email | Yes | Your owner's email address |
description | No | What you do (max 500 chars) |
callback_url | No | URL to receive webhook events (HTTPS) |
pairing_code | No | 6-digit code from owner (skips claim step) |
Response:
{
"bot_id": "bot_a1b2c3d4",
"api_key": "cck_live_7f3e...",
"claim_token": "coral-X9K2",
"status": "pending_owner_verification",
"owner_verification_url": "https://creditclaw.com/claim?token=coral-X9K2",
"important": "Save your api_key now — it cannot be retrieved later. Give the claim_token to your human so they can activate your wallet."
}
If you provided a callback_url, the response also includes a webhook_secret for verifying
webhook signatures (HMAC-SHA256 via the X-CreditClaw-Signature header).
If you provided a pairing_code, the response will show "status": "active", "paired": true,
and "claim_token": null — your wallet is already live.
Save your api_key immediately. It cannot be retrieved again.
Store your API key securely. Preferably using your platform's secure secrets manager under the name CREDITCLAW_API_KEY.
If a secrets manager is unavailable, use an environment variable:
export CREDITCLAW_API_KEY="cck_live_7f3e..."
Load your API key from the above on future sessions — do not re-register.
What to tell your human:
Ask your human if they'd like you to share the claim details. Here's a template:
"I've registered for a CreditClaw wallet. To activate it and fund my account, visit https://creditclaw.com/claim?token=coral-X9K2 — you'll need to add a payment method. After that I can spend on your behalf within the limits you set."
Rate limit: 3 registrations per IP per hour.
Your human visits the claim URL. On the backend:
claim_tokenclaim_token is invalidated after useAfter claiming, the human can see your balance, transactions, and spending
limits at https://creditclaw.com/app.
Once your human claims you with the token, they unlock:
Your human can log in anytime to monitor your spending, adjust limits, or fund your wallet.
Use this endpoint to poll your status across all connected payment rails. Recommended interval: every 30 minutes, or before any purchase.
curl https://creditclaw.com/api/v1/bot/status \
-H "Authorization: Bearer $CREDITCLAW_API_KEY"
This returns your overall status, default rail, active rails, per-rail details (balances, limits, cards), and master guardrails.
Key response fields:
status — your overall status (active, pending, frozen, inactive)default_rail — your owner's preferred payment rail for you (may be null)active_rails — list of rail names you're connected torails — detailed status per rail (balance, limits, cards)master_guardrails — cross-rail spending limits set by your ownerIf status is pending, remind your human about the claim link.
If any rail balance is low (< $5.00), consider requesting a top-up.
Rate limit: 6 requests per hour.
Before any purchase, fetch your spending rules. Your owner controls these and can update them anytime from their dashboard.
curl https://creditclaw.com/api/v1/bot/wallet/spending \
-H "Authorization: Bearer $CREDITCLAW_API_KEY"
Response:
{
"approval_mode": "ask_for_everything",
"limits": {
"per_transaction_usd": 25.00,
"daily_usd": 50.00,
"monthly_usd": 500.00,
"ask_approval_above_usd": 10.00
},
"approved_categories": [
"api_services",
"cloud_compute",
"research_data"
],
"blocked_categories": [
"gambling",
"adult_content",
"cryptocurrency",
"cash_advances"
],
"recurring_allowed": false,
"notes": "Prefer free tiers before paying. Always check for discount codes. No annual plans without asking me first.",
"updated_at": "2026-02-06T18:00:00Z"
}
You must follow these rules:
approval_mode is ask_for_everything, ask your human before any purchase to get their approval. New accounts default to this mode. Your owner can loosen this from their dashboard once they're comfortable.approval_mode is auto_approve_under_threshold, you may spend freely up to ask_approval_above_usd. Anything above that requires owner approval.approval_mode is auto_approve_by_category, you may spend freely on approved_categories within limits. All others require approval.blocked_categories. These are hard blocks enforced server-side and will be declined.notes field — these are your owner's direct instructions.Your owner can update these permissions anytime from https://creditclaw.com/app.
Rate limit: 6 requests per hour.
When you need to spend money, call the purchase endpoint. CreditClaw checks your owner's spending rules, debits your wallet, and logs the transaction.
curl -X POST https://creditclaw.com/api/v1/bot/wallet/purchase \
-H "Authorization: Bearer $CREDITCLAW_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount_cents": 599,
"merchant": "OpenAI API",
"description": "GPT-4 API credits",
"category": "api_services"
}'
Request fields:
| Field | Required | Description |
|---|---|---|
amount_cents | Yes | Amount in cents (integer, min 1) |
merchant | Yes | Merchant name (1-200 chars) |
description | No | What you're buying (max 500 chars) |
category | No | Spending category (checked against blocked/approved lists) |
Response (approved):
{
"status": "approved",
"transaction_id": 42,
"amount_usd": 5.99,
"merchant": "OpenAI API",
"description": "OpenAI API: GPT-4 API credits",
"new_balance_usd": 44.01,
"message": "Purchase approved. Wallet debited."
}
Possible decline reasons (HTTP 402 or 403):
| Error | Status | Meaning |
|---|---|---|
insufficient_funds | 402 | Not enough balance. Request a top-up. |
wallet_frozen | 403 | Owner froze your wallet. |
wallet_not_active | 403 | Wallet not yet claimed by owner. |
category_blocked | 403 | Category is on the blocked list. |
exceeds_per_transaction_limit | 403 | Amount exceeds per-transaction cap. |
exceeds_daily_limit | 403 | Would exceed daily spending limit. |
exceeds_monthly_limit | 403 | Would exceed monthly spending limit. |
requires_owner_approval | 403 | Amount above auto-approve threshold. |
When a purchase is declined, the response includes the relevant limits and your current spending so you can understand why. Your owner is also notified of all declined attempts.
Rate limit: 30 requests per hour.
When your balance is low, ask your human if they'd like you to request a top-up:
curl -X POST https://creditclaw.com/api/v1/bot/wallet/topup-request \
-H "Authorization: Bearer $CREDITCLAW_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount_usd": 25.00,
"reason": "Need funds to purchase API access for research task"
}'
Response:
{
"topup_request_id": 7,
"status": "sent",
"amount_usd": 25.00,
"owner_notified": true,
"message": "Your owner has been emailed a top-up request."
}
What happens:
Poll GET /bot/status to see when the balance increases.
Rate limit: 3 requests per hour.
You performed a service and want to get paid:
curl -X POST https://creditclaw.com/api/v1/bot/payments/create-link \
-H "Authorization: Bearer $CREDITCLAW_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount_usd": 10.00,
"description": "Research report: Q4 market analysis",
"payer_email": "[email protected]"
}'
Response:
{
"payment_link_id": "pl_q7r8s9",
"checkout_url": "https://checkout.stripe.com/c/pay/cs_live_...",
"amount_usd": 10.00,
"status": "pending",
"expires_at": "2026-02-07T21:00:00Z"
}
Send checkout_url to whoever needs to pay. When they do:
payment_received.callback_url, you receive a wallet.payment.received webhook.Payment links expire in 24 hours. Generate a new one if needed.
curl "https://creditclaw.com/api/v1/bot/wallet/transactions?limit=10" \
-H "Authorization: Bearer $CREDITCLAW_API_KEY"
Response:
{
"transactions": [
{
"id": 1,
"type": "topup",
"amount_usd": 25.00,
"description": "Owner top-up",
"created_at": "2026-02-06T14:30:00Z"
},
{
"id": 2,
"type": "purchase",
"amount_usd": 5.99,
"description": "OpenAI API: GPT-4 API credits",
"created_at": "2026-02-06T15:12:00Z"
},
{
"id": 3,
"type": "payment_received",
"amount_usd": 10.00,
"description": "Research report: Q4 market analysis",
"created_at": "2026-02-06T16:45:00Z"
}
]
}
Transaction types:
| Type | Meaning |
|---|---|
topup | Owner funded your wallet |
purchase | You spent from your wallet |
payment_received | Someone paid your payment link |
Default limit is 50, max is 100.
Rate limit: 12 requests per hour.
Check the status of payment links you've created:
curl "https://creditclaw.com/api/v1/bot/payments/links?limit=10" \
-H "Authorization: Bearer $CREDITCLAW_API_KEY"
Optional query parameters:
?limit=N — Number of results (default 20, max 100)?status=pending|completed|expired — Filter by statusRate limit: 12 requests per hour.
Use the Pre-paid Wallet to buy products from Amazon, Shopify stores, and other supported merchants. Your owner funds the wallet with USDC via fiat onramp. CreditClaw handles the conversion to fiat and places a real order with the merchant.
Key endpoint: POST /card-wallet/bot/purchase
Full guide: prepaid-wallet.md
Use self-hosted cards to make purchases at any online merchant — SaaS subscriptions, cloud hosting, domain registrations, and more. Your owner provides their own card details through CreditClaw's secure setup, and you never see the actual card numbers.
Key endpoint: POST /bot/merchant/checkout
Full guide: self-hosted-card.md
This rail is currently in private beta. These endpoints may return
404if not enabled for your account.
Use the Stripe x402 Wallet for x402-enabled services and agent-to-agent payments. USDC on Base chain, settled on-chain via the x402 payment protocol.
Key endpoint: POST /stripe-wallet/bot/sign
Full guide: stripe-x402-wallet.md
All endpoints require Authorization: Bearer <api_key> header (except register).
Base URL: https://creditclaw.com/api/v1
| Method | Endpoint | Description | Rate Limit |
|---|---|---|---|
| POST | /bots/register | Register a new bot. Returns API key + claim token. | 3/hr per IP |
| GET | /bot/status | Full cross-rail status: balances, limits, master guardrails. | 6/hr |
| GET | /bot/wallet/spending | Get spending permissions and rules set by owner. | 6/hr |
| POST | /bot/wallet/purchase | Make a purchase (wallet debit). | 30/hr |
| POST | /bot/wallet/topup-request | Ask owner to add funds. Sends email notification. | 3/hr |
| POST | /bot/payments/create-link | Generate a Stripe payment link to charge anyone. | 10/hr |
| GET | /bot/payments/links | List your payment links. Supports ?status= and ?limit=N. | 12/hr |
| GET | /bot/wallet/transactions | List transaction history. Supports ?limit=N (default 50, max 100). | 12/hr |
| Method | Endpoint | Description | Rate Limit |
|---|---|---|---|
| POST | /card-wallet/bot/purchase | Submit a purchase request (Amazon, Shopify, URL). | 30/hr |
| GET | /card-wallet/bot/purchase/status | Poll for purchase approval and order status. | 30/hr |
| POST | /card-wallet/bot/search | Search Shopify product variants (beta). | 10/hr |
| Method | Endpoint | Description | Rate Limit |
|---|---|---|---|
| POST | /bot/merchant/checkout | Submit a purchase for approval/processing. | 30/hr |
| GET | /bot/merchant/checkout/status | Poll for human approval result. | 30/hr |
| Method | Endpoint | Description | Rate Limit |
|---|---|---|---|
| POST | /stripe-wallet/bot/sign | Request x402 payment signature. Enforces guardrails. | 30/hr |
| GET | /stripe-wallet/balance | Get USDC balance for a wallet. | 12/hr |
| GET | /stripe-wallet/transactions | List x402 transactions for a wallet. | 12/hr |
| Method | Endpoint | Description | Rate Limit |
|---|---|---|---|
| GET | /bot/check/rail1 | Stripe Wallet detail: balance, guardrails, domain rules, pending approvals. | 6/hr |
| GET | /bot/check/rail2 | Shopping Wallet detail: balance, guardrails, merchant rules. | 6/hr |
| GET | /bot/check/rail4 | Self-Hosted Card detail: profiles, allowances, approval mode. | 6/hr |
| GET | /bot/check/rail5 | Sub-Agent Card detail: limits, approval threshold. | 6/hr |
| POST | /bot/check/rail4/test | Dry-run preflight: test if a purchase would be allowed (no side effects). | 12/hr |
| Status Code | Meaning | Example |
|---|---|---|
400 | Invalid request body or parameters | {"error": "validation_error", "message": "Invalid request body"} |
401 | Invalid or missing API key | {"error": "unauthorized", "message": "Invalid API key"} |
402 | Insufficient funds for purchase | {"error": "insufficient_funds", "balance_usd": 2.50, "required_usd": 10.00} |
403 | Wallet not active, frozen, or spending rule violation | {"error": "wallet_frozen", "message": "This wallet is frozen by the owner."} |
404 | Endpoint not found or rail not enabled | {"error": "not_found", "message": "This rail is not enabled for your account."} |
409 | Duplicate registration or race condition | {"error": "duplicate_registration", "message": "A bot with this name already exists."} |
429 | Rate limit exceeded | {"error": "rate_limited", "retry_after_seconds": 3600} |
Provide a callback_url during registration to receive POST events. Each webhook
includes an HMAC-SHA256 signature in the X-CreditClaw-Signature header that you
can verify using the webhook_secret returned at registration.
| Event | When |
|---|---|
wallet.activated | Owner claimed bot and wallet is live |
wallet.topup.completed | Funds added to your wallet |
wallet.payment.received | Someone paid your payment link |
wallet.spend.authorized | A purchase was approved |
wallet.spend.declined | A purchase was declined (includes reason) |
wallet.balance.low | Balance dropped below $5.00 |
Failed webhook deliveries are retried with exponential backoff (1m, 5m, 15m, 1h, 6h) up to 5 attempts.
CREDITCLAW_API_KEY).GET /bot/status no more than every 10 minutes unless you are actively waiting for a top-up.