Bots

Endpoints for registering bots, checking bot status, initiating purchases, polling purchase approval status, and fetching scheduled tasks.

Register a Bot

Creates a new bot and returns an API key for authentication.

Request Body

Response

201 Created — without pairing code (pending owner verification):

{
  "bot_id": "bot_a1b2c3d4e5",
  "api_key": "cck_live_abc123...",
  "claim_token": "clm_xyz789...",
  "status": "pending_owner_verification",
  "owner_verification_url": "https://creditclaw.com/claim?token=clm_xyz789...",
  "webhook_secret": "whsec_...",
  "webhook_note": "Save your webhook_secret now — it cannot be retrieved later.",
  "important": "Save your api_key now — it cannot be retrieved later. Give the claim_token to your human so they can activate your wallet."
}

201 Created — with pairing code (instantly active):

{
  "bot_id": "bot_a1b2c3d4e5",
  "api_key": "cck_live_abc123...",
  "claim_token": null,
  "status": "active",
  "paired": true,
  "owner_uid": "firebase_uid_...",
  "webhook_secret": "whsec_...",
  "important": "Save your api_key now — it cannot be retrieved later. Your wallet is already active via pairing code."
}

201 Created — without callback_url (managed tunnel provisioned):

{
  "bot_id": "bot_a1b2c3d4e5",
  "api_key": "cck_live_abc123...",
  "claim_token": "clm_xyz789...",
  "status": "pending_owner_verification",
  "owner_verification_url": "https://creditclaw.com/claim?token=clm_xyz789...",
  "webhook_secret": "whsec_...",
  "webhook_url": "https://bot-a1b2c3d4e5.nortonbot.com/hooks/creditclaw",
  "tunnel_token": "eyJ...",
  "tunnel_setup": {
    "webhook_url": "https://bot-a1b2c3d4e5.nortonbot.com/hooks/creditclaw",
    "tunnel_token": "eyJ...",
    "cloudflared_command": "cloudflared tunnel run --token eyJ...",
    "local_port": 18789,
    "webhook_path": "/hooks/creditclaw",
    "steps": ["1. Install cloudflared...", "2. Run: cloudflared tunnel run --token ..."],
    "webhook_headers": {
      "X-CreditClaw-Signature": "sha256=<hmac>",
      "X-CreditClaw-Event": "<event_type>"
    },
    "retry_policy": "Failed deliveries are retried up to 5 times with exponential backoff.",
    "openclaw_gateway_config": "..."
  },
  "openclaw_hooks_token": "whsec_...",
  "openclaw_hooks_token_note": "Save your openclaw_hooks_token now — it cannot be retrieved later. Set it as CREDITCLAW_HOOKS_TOKEN in your OpenClaw environment.",
  "important": "Save your api_key now — it cannot be retrieved later."
}

The tunnel_setup object contains everything needed to connect the tunnel. See Webhook Setup & Signing for delivery format and signature verification.

Important: The api_key, webhook_secret, and openclaw_hooks_token (if present) are only returned once at registration. Store them securely — they cannot be retrieved again.

Errors

Examples

With your own webhook endpoint:

curl -X POST https://creditclaw.com/api/v1/bots/register \
  -H "Content-Type: application/json" \
  -d '{
    "bot_name": "ShopperBot",
    "owner_email": "owner@example.com",
    "description": "Autonomous shopping assistant",
    "callback_url": "https://mybot.example.com/webhooks"
  }'

Without a webhook endpoint (managed tunnel):

curl -X POST https://creditclaw.com/api/v1/bots/register \
  -H "Content-Type: application/json" \
  -d '{
    "bot_name": "ShopperBot",
    "owner_email": "owner@example.com",
    "description": "Autonomous shopping assistant",
    "bot_type": "openclaw"
  }'

Get Bot Status

Returns the bot's current status, active payment rails, spending limits, and master guardrails.

Response

200 OK — active bot with rails:

{
  "bot_id": "bot_a1b2c3d4e5",
  "bot_name": "ShopperBot",
  "status": "active",
  "default_rail": "rail5",
  "active_rails": ["card_wallet", "stripe_wallet"],
  "rails": {
    "card_wallet": {
      "status": "active",
      "balance_usd": 42.50,
      "spending_limits": {
        "per_transaction_usd": 50,
        "monthly_usd": 500,
        "monthly_spent_usd": 127.30,
        "monthly_remaining_usd": 372.70
      }
    },
    "stripe_wallet": {
      "status": "active",
      "balance_usd": 100.00,
      "address": "0x..."
    }
  },
  "master_guardrails": {
    "per_transaction_usd": 100,
    "daily_budget_usd": 200,
    "monthly_budget_usd": 1000
  },
  "pending_messages": 0,
  "webhook_status": "active",
  "webhook_fail_count": 0
}

200 OK — pending bot (not yet claimed by owner):

{
  "bot_id": "bot_a1b2c3d4e5",
  "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
}

The status field can be:

Example

curl https://creditclaw.com/api/v1/bot/status \
  -H "Authorization: Bearer cck_live_abc123..."

Initiate a Purchase

Requests a purchase through the bot's encrypted card rail. The request goes through guardrail evaluation and may require owner approval.

Request Body

Guardrail Evaluation Flow

When a purchase request is submitted, it passes through multiple guardrail checks:

1. Wallet status — wallet must be active and not frozen
2. Card guardrails — per-transaction limits, daily/monthly budgets
3. Profile allowance — per-profile spending limits within the configured window
4. Master guardrails — owner-level spending limits (for real profile purchases)
5. Approval mode — determines if human approval is required

Response

200 OK — approved immediately:

{
  "approved": true,
  "missing_digits": "4321",
  "expiry_month": "12",
  "expiry_year": "2026",
  "confirmation_id": "chk_a1b2c3d4e5f6",
  "profile_index": 0,
  "merchant_name": "Amazon",
  "amount_usd": 19.99,
  "message": "Checkout approved. Enter the provided card details to complete your purchase."
}

202 Accepted — pending owner approval:

{
  "approved": false,
  "status": "pending_confirmation",
  "confirmation_id": "chk_a1b2c3d4e5f6",
  "profile_index": 0,
  "merchant_name": "Amazon",
  "amount_usd": 19.99,
  "expires_at": "2025-01-15T12:30:00.000Z",
  "message": "This purchase requires owner approval. Poll /api/v1/bot/merchant/checkout/status to check the result."
}

When you receive a 202, poll the checkout status endpoint until the status resolves.

Errors

Example

curl -X POST https://creditclaw.com/api/v1/bot/merchant/checkout \
  -H "Authorization: Bearer cck_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "profile_index": 0,
    "merchant_name": "Amazon",
    "merchant_url": "https://amazon.com/dp/B09XYZ",
    "item_name": "USB-C Hub",
    "amount_cents": 2499,
    "category": "retail"
  }'

Check Purchase Status

Poll this endpoint to check whether a pending purchase has been approved, denied, or expired.

Query Parameters

Response

200 OK — approved:

{
  "confirmation_id": "chk_a1b2c3d4e5f6",
  "status": "approved",
  "amount_usd": 24.99,
  "merchant_name": "Amazon",
  "item_name": "USB-C Hub",
  "missing_digits": "4321",
  "expiry_month": "12",
  "expiry_year": "2026",
  "message": "Purchase approved. Use the provided card details to complete checkout."
}

200 OK — pending:

{
  "confirmation_id": "chk_a1b2c3d4e5f6",
  "status": "pending",
  "amount_usd": 24.99,
  "merchant_name": "Amazon",
  "item_name": "USB-C Hub",
  "message": "Waiting for owner approval."
}

200 OK — denied:

{
  "confirmation_id": "chk_a1b2c3d4e5f6",
  "status": "denied",
  "amount_usd": 24.99,
  "merchant_name": "Amazon",
  "item_name": "USB-C Hub",
  "message": "Purchase was denied by the owner."
}

The status field can be:

Example

curl "https://creditclaw.com/api/v1/bot/merchant/checkout/status?confirmation_id=chk_a1b2c3d4e5f6" \
  -H "Authorization: Bearer cck_live_abc123..."

Recommended polling pattern: Check every 5 seconds for the first minute, then every 15 seconds until expiry.

Fetch Next Task

Retrieves the next scheduled task for the bot, if any are available.

Response

200 OK — task available:

{
  "has_task": true,
  "task_type": "purchase",
  "task_id": "task_42",
  "instructions": {
    "profile_index": 1,
    "merchant_name": "CloudServe Pro",
    "merchant_url": "/merchant/cloudserve-pro",
    "item_name": "Monthly hosting plan",
    "amount_cents": 1299,
    "category": "saas"
  },
  "message": "Purchase \"Monthly hosting plan\" from CloudServe Pro using Payment Profile #1."
}

200 OK — no tasks:

{
  "has_task": false,
  "message": "No tasks at this time. Check back later."
}

When a task is returned, fulfill it by calling the checkout endpoint with the provided instructions and including the task_id in the request body.

Example

curl -X POST https://creditclaw.com/api/v1/bot/tasks/next \
  -H "Authorization: Bearer cck_live_abc123..."

Related

• Authentication — how to get and use API keys
• Wallets — check balance and request top-ups
• Webhooks — receive async notifications for purchases and approvals
• Quick Start — end-to-end bot setup walkthrough