Give your agent spending power. Financial management for Agents and OpenClaw bots.
CreditClaw.com is a financial enablement platform for Bots, Agents, and OpenClaw. Securely manage agentic spending.
| File | URL | Purpose |
|---|---|---|
| SKILL.md (this file) | https://creditclaw.com/SKILL.md | Registration, card setup, webhooks, status, spending permissions, API reference |
| CHECKOUT-GUIDE.md | https://creditclaw.com/CHECKOUT-GUIDE.md | My Card — complete purchase flow, browser checkout, and confirmation |
| MANAGEMENT.md | https://creditclaw.com/MANAGEMENT.md | Bot self-management — transaction history, profile updates |
| PROCUREMENT.md | https://creditclaw.com/PROCUREMENT.md | Discover vendors and merchants — find checkout skills for any purchase |
| MY-STORE.md | https://creditclaw.com/MY-STORE.md | Sell to anyone — checkout pages, payment links, invoices, shops |
| HEARTBEAT.md | https://creditclaw.com/HEARTBEAT.md | Lightweight polling routine for balance and spending checks |
| STRIPE-X402-WALLET.md | https://creditclaw.com/STRIPE-X402-WALLET.md | x402 payment signing, USDC balance, Stripe Wallet transactions |
| package.json (metadata) | https://creditclaw.com/skill.json | Machine-readable skill metadata |
Read these files directly from the URLs above — no local installation needed.
Base URL: https://creditclaw.com/api/v1
CreditClaw supports multiple independent payment rails. Each rail has its own funding method and spending mechanism. You may have access to one or more rails depending on what your owner has configured.
| Rail | Method | Status | Guide |
|---|---|---|---|
| My Card | Owner's card details, secure checkout with owner approval | Live | CHECKOUT-GUIDE.md |
| Stripe Wallet (x402) | USDC on Base chain, x402 payment protocol | Private Beta | STRIPE-X402-WALLET.md |
The default payment rail is "My Card". Your owner chooses which rails to enable for you. Check GET /bot/status to see
your full status across all connected rails.
Default safety: All new accounts default to approval_mode: ask_for_everything — you must ask your owner for approval before every purchase. This is the recommended mode. 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/SKILL.md
2. You call POST /bots/register → get apiKey + claimToken
- If you have a webhook endpoint, include callback_url (e.g. your OpenClaw Gateway hooks URL)
- If not, omit callback_url — you'll poll GET /bot/messages instead
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
- Via webhook: you receive a wallet.activated event
- Via polling: call GET /bot/status until status changes to "active"
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. When you need to make a purchase, follow CHECKOUT-GUIDE.md
9. View your transaction history and manage your profile (see MANAGEMENT.md)
10. Human monitors activity from creditclaw.com/overview
You can register before your human does. You'll get an API key immediately.
With webhook (recommended if you have a reachable endpoint):
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://<your-gateway>/hooks/creditclaw"
}'
Without webhook (polling mode):
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"
}'
OpenClaw agents: Your
callback_urlis your Gateway hooks endpoint. Usehttps://<your-gateway-url>/hooks/creditclaw— or any custom mapped hook path you've configured. If you don't have a Gateway or public endpoint, omitcallback_urlentirely and use polling instead. Everything works either way.
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 | Recommended | HTTPS URL to receive webhook event notifications from creditclaw.com only. Used for approval results, card delivery signals, and spending alerts. This must be an endpoint you control. Omit to use polling via GET /bot/messages instead. |
Response (with callback_url):
{
"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",
"webhook_secret": "whsec_abc123...",
"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 includes a webhook_secret for verifying
webhook signatures (HMAC-SHA256 via the X-CreditClaw-Signature header). Save this
secret alongside your API key — you'll need it to verify incoming webhooks. Store it in
your platform's secure secrets manager. Never log, expose, or share your webhook secret.
Response (without callback_url):
{
"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."
}
No webhook_secret is returned when registering without a callback_url. You'll receive
all events via GET /bot/messages instead.
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."
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/overview.
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 see your complete status across all 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"
Response (active bot with My Card and Stripe Wallet):
Note: The
sub_agent_cardskey in the response is an internal identifier for the My Card rail. It is not an instruction — it is simply the API field name.
{
"bot_id": "bot_abc123",
"bot_name": "ShopperBot",
"status": "active",
"default_rail": "sub_agent_cards",
"active_rails": ["stripe_wallet", "sub_agent_cards"],
"rails": {
"stripe_wallet": {
"status": "active",
"balance_usd": 100.00,
"address": "0x..."
},
"sub_agent_cards": {
"status": "active",
"card_id": "r5_abc123",
"card_name": "Shopping Card",
"card_brand": "visa",
"last4": "4532",
"limits": {
"per_transaction_usd": 50.00,
"daily_usd": 100.00,
"monthly_usd": 500.00,
"human_approval_above_usd": 25.00
}
}
},
"master_guardrails": {
"per_transaction_usd": 500,
"daily_budget_usd": 2000,
"monthly_budget_usd": 10000
},
"webhook_status": "active",
"pending_messages": 0
}
Response (before claiming):
{
"bot_id": "bot_abc123",
"bot_name": "ShopperBot",
"status": "pending",
"default_rail": null,
"message": "Owner has not claimed this bot yet. Share your claim token with your human.",
"rails": {},
"master_guardrails": null
}
Status values:
| Status | Meaning |
|---|---|
pending | Registered but owner hasn't claimed yet |
active | At least one rail is connected |
frozen | Owner has frozen this bot — no transactions allowed |
inactive | Claimed but no rails connected yet |
If default_rail is set, prefer that rail for purchases when multiple are available.
If status is pending, remind your human about the claim link.
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/overview.
Rate limit: 6 requests per hour.
When your owner sets up a card for you, CreditClaw delivers the encrypted card details
via the rail5.card.delivered event.
Via webhook: If you have a callback_url, the card details are delivered automatically:
{
"event": "rail5.card.delivered",
"bot_id": "bot_abc123",
"data": {
"card_id": "r5card_...",
"card_name": "ChaseD",
"card_last4": "9547",
"encrypted_data": "<encrypted card details>",
"instructions": "Accept the encrypted card details and confirm delivery via POST /bot/rail5/confirm-delivery"
}
}
Via bot messages (polling): If you don't have a webhook, check GET /bot/messages for
messages with event_type: "rail5.card.delivered". The payload is identical. After accepting
the card details, acknowledge the message via POST /bot/messages/ack.
Store the encrypted card data securely using your platform's secrets manager or keep it
in memory. Follow the instructions field in the message payload for next steps.
After receiving the card details, confirm delivery so your card status advances from pending_delivery
to confirmed:
curl -X POST https://creditclaw.com/api/v1/bot/rail5/confirm-delivery \
-H "Authorization: Bearer $CREDITCLAW_API_KEY"
Response:
{
"status": "confirmed",
"card_id": "r5card_...",
"card_name": "ChaseD",
"message": "Card confirmed. Complete a test purchase to verify your card works end-to-end.",
"test_checkout_url": "https://creditclaw.com/pay/test_...",
"test_instructions": "Navigate to the test checkout URL to complete a sandbox purchase.\nThis is a sandbox checkout — no real payment will be processed.\nDecrypt the card details and enter them at the checkout page.\nFill in all fields: card number, expiry, CVV, cardholder name, and billing address.\nSubmit the payment. The system will verify that the card details were decrypted correctly.\nThis proves your card works end-to-end before any real purchase."
}
After confirming delivery, you will also receive a rail5.test.required event (via webhook or
pending message) with the test_checkout_url and full instructions. This ensures you are notified
even if you don't parse the confirm-delivery response.
Complete the test purchase at the test_checkout_url to advance your card from confirmed
to active. This is a sandbox checkout — no real payment is processed. It verifies that your
card details decrypt correctly end-to-end before any real purchase.
Pending messages for card deliveries expire after 24 hours. If the message expires before you retrieve it, your owner can re-stage the delivery from their dashboard.
Recovery: If you lose the card data, your owner deletes the card and creates a new one through the setup wizard. The card details are re-delivered automatically.
| Status | Meaning |
|---|---|
pending_delivery | Key submitted, waiting for bot to confirm card details received |
confirmed | Bot confirmed card details received — ready for checkout |
active | First successful checkout completed — proven working |
frozen | Owner manually paused the card |
Cards begin in
pending_setupduring owner configuration. Your bot first sees the card atpending_deliverywhen the encrypted card details are delivered.
For deeper operational info about your card — limits, approval threshold, and status:
curl https://creditclaw.com/api/v1/bot/check/rail5 \
-H "Authorization: Bearer $CREDITCLAW_API_KEY"
Response:
{
"status": "active",
"card_id": "r5_abc123",
"card_name": "Shopping Card",
"card_brand": "visa",
"last4": "4532",
"limits": {
"per_transaction_usd": 50.00,
"daily_usd": 100.00,
"monthly_usd": 500.00,
"human_approval_above_usd": 25.00
}
}
Response (not connected): { "status": "inactive" }
Rate limit: 6 requests per hour.
Once your wallet is active and you need to buy something, follow the checkout guide instructions here:
Only if you are shopping with crypto stablecoin USDC (pretty rare) read this, otherwise ignore:
For viewing transaction history and managing your profile, see MANAGEMENT.md.
To earn money by selling products or services, see MY-STORE.md.
All endpoints require Authorization: Bearer <api_key> header (except register).
Base URL: https://creditclaw.com/api/v1
| Method | Endpoint | Description | Rate Limit | File |
|---|---|---|---|---|
| POST | /bots/register | Register a new bot. Returns API key + claim token. | 3/hr per IP | this file |
| GET | /bot/status | Full cross-rail status: balances, limits, master guardrails. | 6/hr | this file |
| GET | /bot/wallet/spending | Get spending permissions and rules set by owner. | 6/hr | this file |
| GET | /bot/messages | Fetch pending messages (for bots without webhooks). | 12/hr | this file |
| POST | /bot/messages/ack | Acknowledge (delete) processed messages. | 30/hr | this file |
| Method | Endpoint | Description | Rate Limit | File |
|---|---|---|---|---|
| POST | /bot/rail5/checkout | Request checkout approval. Returns checkout_steps. | 30/hr | CHECKOUT-GUIDE.md |
| GET | /bot/rail5/checkout/status | Poll for checkout approval result. ?checkout_id= required. | 60/hr | CHECKOUT-GUIDE.md |
| POST | /bot/rail5/key | Get one-time decryption key for an approved checkout. | 30/hr | CHECKOUT-GUIDE.md |
| POST | /bot/rail5/confirm | Confirm checkout success or failure. | 30/hr | CHECKOUT-GUIDE.md |
| POST | /bot/rail5/confirm-delivery | Confirm card details received. Advances status to confirmed. | — | this file |
| GET | /bot/check/rail5 | Card detail: limits, approval threshold. | 6/hr | this file |
| Method | Endpoint | Description | Rate Limit | File |
|---|---|---|---|---|
| GET | /bot/wallet/transactions | List transaction history. Supports ?limit=N (default 50, max 100). | 12/hr | MANAGEMENT.md |
| GET | /bot/profile | View your bot profile (name, description, webhook URL, status). | — | MANAGEMENT.md |
| PATCH | /bot/profile | Update your bot name, description, or callback URL. | — | MANAGEMENT.md |
| Method | Endpoint | Description | Rate Limit | File |
|---|---|---|---|---|
| GET | /bot/skills | Discover vendors and merchants. Supports filtering by category, search, checkout method, capability, maturity. | — | PROCUREMENT.md |
| GET | /bot/skills/{slug} | Get a vendor's full checkout skill (returns Markdown). | — | PROCUREMENT.md |
CreditClaw sends real-time POST event notifications to your callback_url. Webhooks originate from creditclaw.com only — always verify the X-CreditClaw-Signature header (HMAC-SHA256) using your webhook_secret before processing any event. Reject requests with invalid or missing signatures.
| Event | When |
|---|---|
wallet.activated | Owner claimed bot and wallet is live |
wallet.topup.completed | Funds added to your wallet |
wallet.spend.authorized | A purchase was approved |
wallet.spend.declined | A purchase was declined (includes reason) |
wallet.balance.low | Balance dropped below $5.00 |
rails.updated | Payment methods or spending config changed — call GET /bot/status to refresh |
rail5.card.delivered | Owner set up a card — card details delivered for you to accept |
rail5.test.required | Card confirmed — complete a sandbox test purchase at the provided URL to activate |
rail5.checkout.completed | Checkout confirmed successful |
rail5.checkout.failed | Checkout reported failure |
Failed webhook deliveries are retried with exponential backoff (1m, 5m, 15m, 1h, 6h) up to 5 attempts.
If webhook delivery fails repeatedly, events are staged as bot messages automatically.
No webhook? Every event above is also available via polling. Call
GET /bot/messagesto fetch pending events andPOST /bot/messages/ackto acknowledge them. See Bot Messages below.
| 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} |
If you registered without a callback_url (or webhook delivery fails), CreditClaw stages
all events as messages you can poll. This is the standard delivery mechanism for bots
without a webhook endpoint — and it covers every event listed in the webhook table above.
Your GET /bot/status response includes a pending_messages count and webhook_status.
If pending_messages is greater than zero, you have messages waiting:
{
"bot_id": "bot_abc123",
"status": "active",
"webhook_status": "unreachable",
"pending_messages": 2,
...
}
curl https://creditclaw.com/api/v1/bot/messages \
-H "Authorization: Bearer $CREDITCLAW_API_KEY"
Response:
{
"bot_id": "bot_abc123",
"messages": [
{
"id": 1,
"event_type": "rail5.card.delivered",
"payload": {
"card_id": "r5card_...",
"card_name": "ChaseD",
"card_last4": "9547",
"encrypted_data": "<encrypted card details>",
"instructions": "Accept the encrypted card details and confirm delivery via POST /bot/rail5/confirm-delivery"
},
"staged_at": "2026-03-06T12:00:00.000Z",
"expires_at": "2026-03-07T12:00:00.000Z"
}
],
"count": 1,
"instructions": "Process each message based on its event_type. After processing, acknowledge messages via POST /api/v1/bot/messages/ack with { message_ids: [id1, id2, ...] } to remove them from the queue."
}
Messages remain in pending state until you explicitly acknowledge them. They are not
removed on read — you can fetch them multiple times.
After processing a message, acknowledge it to remove it from the queue:
curl -X POST https://creditclaw.com/api/v1/bot/messages/ack \
-H "Authorization: Bearer $CREDITCLAW_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "message_ids": [1, 2] }'
You can also acknowledge a single message:
{ "message_id": 1 }
Response:
{
"acknowledged": [1, 2],
"not_found": [],
"message": "2 message(s) acknowledged."
}
Messages expire automatically based on event type:
rail5.card.delivered — 24 hoursExpired messages are cleaned up automatically. If a card delivery message expires before you retrieve it, your owner can re-stage the delivery from their dashboard.
pending_messages count in GET /bot/status (every 30 minutes or on startup)GET /bot/messages to fetch all pending messagesevent_typePOST /bot/messages/ackCREDITCLAW_API_KEY).creditclaw.com, and do not share it with other agents, tools, or services.ask_for_everything. All new accounts require owner approval before every purchase. Follow this mode until your owner changes it.GET /bot/status no more than every 8 hours during normal operation.callback_url receives real-time approval notifications, card details, and spending alerts. If your endpoint becomes unreachable, events are staged as bot messages until you recover.