CreditClaw — Amazon Shopping for AI Agents

---

name: creditclaw-amazon

version: 2.2.4

updated: 2026-02-14T21:30:00Z

description: "Let your agent shop on Amazon with guardrailed wallets and owner approval."

homepage: https://creditclaw.com

api_base: https://creditclaw.com/api/v1

credentials: [CREDITCLAW_API_KEY]

metadata: {"openclaw":{"requires":{"env":["CREDITCLAW_API_KEY"]},"primaryEnv":"CREDITCLAW_API_KEY"}}

---

# CreditClaw — Amazon Shopping for AI Agents

CreditClaw lets your agent buy products on Amazon with owner-controlled spending limits and approval flows.

Your owner funds a wallet, sets guardrails, and you shop within those limits.

Skill Files

| File | URL | Purpose |

|------|-----|---------|

| **SKILL.md** (this file) | `https://creditclaw.com/amazon/skill.md` | Full API reference and registration instructions |

| **AMAZON.md** | `https://creditclaw.com/amazon/amazon.md` | Amazon purchase guide (ASIN discovery, tracking, restrictions) |

| **HEARTBEAT.md** | `https://creditclaw.com/amazon/heartbeat.md` | Lightweight polling routine for balance and spending checks |

| **package.json** (metadata) | `https://creditclaw.com/amazon/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/amazon
curl -s https://creditclaw.com/amazon/skill.md > ~/.creditclaw/skills/amazon/SKILL.md
curl -s https://creditclaw.com/amazon/amazon.md > ~/.creditclaw/skills/amazon/AMAZON.md
curl -s https://creditclaw.com/amazon/heartbeat.md > ~/.creditclaw/skills/amazon/HEARTBEAT.md
curl -s https://creditclaw.com/amazon/skill.json > ~/.creditclaw/skills/amazon/package.json

Or just read them directly from the URLs above.

**Base URL:** `https://creditclaw.com/api/v1`

---

Payment Rails

CreditClaw supports multiple independent payment rails. **Amazon purchases use Rail 2 (Card Wallet).**

| Rail | Method | Status | Spending Mechanism |

|------|--------|--------|-------------------|

| **Card Wallet (Rail 2)** | USDC wallet on Base chain, Amazon/commerce purchases | Live | `POST /card-wallet/bot/purchase` (owner approval) |

| **Wallet** | Prepaid wallet funded by owner | Live | `POST /bot/wallet/purchase` (direct debit) |

| **Self-Hosted Cards** | Owner's own cards with split-knowledge privacy | Live | `POST /bot/merchant/checkout` (human approval) |

| **Stripe Wallet (x402)** | USDC on Base chain, x402 payment protocol | Private Beta | `POST /stripe-wallet/bot/sign` (guardrail-enforced signing) |

Your owner chooses which rails to enable for you. Check `GET /bot/wallet/check` to see

your active wallet status. For Amazon shopping, you need an active Card Wallet (Rail 2).

**For Amazon-specific purchase details (ASIN discovery, tracking, restrictions), see [amazon.md](https://creditclaw.com/amazon/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.

---

Shopping at Amazon.com

CreditClaw lets you buy physical products on Amazon through Rail 2 (Card Wallet). Your owner funds the wallet with USDC, and CreditClaw handles the conversion to fiat and places a real Amazon order.

**How it works:**

1. You find the product's ASIN (the 10-character code in any Amazon product URL, e.g. `B01DFKC2SO`)

2. You call `POST /card-wallet/bot/purchase` with the ASIN and a US shipping address

3. Your owner approves the purchase (within 15 minutes)

4. Amazon ships the product — you get full tracking (carrier, tracking number, ETA)

**Key facts:**

---

Security

**All requests require:** `Authorization: Bearer <your-api-key>` (except registration).

🔒 **CRITICAL SECURITY WARNING:**

CreditClaw is designed with defense-in-depth to protect your owner's funds:

---

End-to-End Flow

1. You fetch this skill file from creditclaw.com/amazon/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/wallet/check periodically to monitor balance
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.

---

Quick Start

1. Register

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": "jonathan@example.com",
    "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.

2. Human Claims the Bot

Your human visits the claim URL. On the backend:

After claiming, the human can see your balance, transactions, and spending

limits at `https://creditclaw.com/app`.

What Your Human Gets After Claiming

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.

3. Check Wallet Status (Heartbeat)

Use this lightweight endpoint to poll your wallet status. Recommended

interval: every 30 minutes, or before any purchase.

curl https://creditclaw.com/api/v1/bot/wallet/check \
  -H "Authorization: Bearer $CREDITCLAW_API_KEY"

Response (after claiming, with funds):

{
  "wallet_status": "active",
  "balance_usd": 50.00,
  "spending_limits": {
    "per_transaction_usd": 25.00,
    "monthly_usd": 500.00,
    "monthly_spent_usd": 12.50,
    "monthly_remaining_usd": 487.50
  },
  "pending_topups": 0
}

Response (before claiming):

{
  "wallet_status": "pending",
  "balance_usd": 0,
  "message": "Owner has not claimed this bot yet. Share your claim token with your human."
}

**Status values:**

| Status | Meaning |

|--------|---------|

| `pending` | Registered but owner hasn't claimed yet |

| `active` | Wallet funded and ready to use |

| `empty` | Wallet is active but $0 balance — request a top-up |

If `wallet_status` is `pending`, remind your human about the claim link.

If `balance_usd` < 5.00, consider requesting a top-up.

**Rate limit:** 6 requests per hour.

4. Check Spending Permissions (Before Every Purchase)

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:**

Your owner can update these permissions anytime from `https://creditclaw.com/app`.

**Rate limit:** 6 requests per hour.

5. Make a Purchase (Wallet Debit)

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.

6. Request a Top-Up From Your Owner

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/wallet/check` to see when the balance increases.

**Rate limit:** 3 requests per hour.

7. Generate a Payment Link (Charge Anyone)

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": "client@example.com"
  }'

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 links expire in 24 hours.** Generate a new one if needed.

8. View Transaction History

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.

9. List Your Payment Links

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:

**Rate limit:** 12 requests per hour.

---

Self-Hosted Cards (Rail 4)

If your owner has set up self-hosted cards, you can make purchases at online merchants

using a checkout flow with human approval. This rail uses a split-knowledge privacy model —

your owner provides card details through CreditClaw's secure setup, and you never see

the actual card numbers.

How Self-Hosted Card Checkout Works

1. You submit a checkout request with merchant and amount details

2. CreditClaw evaluates the request against your card's permissions

3. If the amount is within your auto-approved allowance, it processes immediately

4. If the amount exceeds the threshold, your owner receives an approval request (email with secure link)

5. You poll for the result

6. Once approved, the transaction is recorded

Make a Self-Hosted Card Checkout

curl -X POST https://creditclaw.com/api/v1/bot/merchant/checkout \
  -H "Authorization: Bearer $CREDITCLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_index": 1,
    "merchant_name": "DigitalOcean",
    "merchant_url": "https://cloud.digitalocean.com",
    "item_name": "Droplet hosting - 1 month",
    "amount_cents": 1200,
    "category": "cloud_compute"
  }'

**Request fields:**

| Field | Required | Description |

|-------|----------|-------------|

| `profile_index` | Yes | The payment profile index assigned to you |

| `merchant_name` | Yes | Merchant name (1-200 chars) |

| `merchant_url` | Yes | Merchant website URL |

| `item_name` | Yes | What you're buying |

| `amount_cents` | Yes | Amount in cents (integer) |

| `card_id` | No | Required if you have multiple cards; auto-selects if only one |

| `category` | No | Spending category |

| `task_id` | No | Your internal task reference |

**Response (auto-approved — within allowance):**

{
  "status": "approved",
  "transaction_id": "txn_abc123",
  "amount_usd": 12.00,
  "message": "Transaction approved within allowance."
}

**Response (requires human approval):**

{
  "status": "pending_approval",
  "confirmation_id": "conf_xyz789",
  "message": "Your owner has been sent an approval request. Poll /bot/merchant/checkout/status to check the result.",
  "expires_in_minutes": 15
}

Poll for Approval Result

If you received `pending_approval`, poll for the result:

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

**Response values:**

| Status | Meaning |

|--------|---------|

| `pending` | Owner hasn't responded yet — poll again in 30 seconds |

| `approved` | Owner approved — proceed with your task |

| `rejected` | Owner declined — do not proceed |

| `expired` | 15-minute approval window passed — try again if needed |

**Multi-card note:** If your owner has linked you to multiple self-hosted cards, you must include `card_id` in

your checkout request. If you only have one active card, `card_id` is optional and will auto-select.

**Rate limit:** 30 requests per hour (checkout), 30 requests per hour (status polling).

---

Stripe Wallet — x402 / USDC (Private Beta)

> **This rail is currently in private beta and not yet available for general use.**

> If your owner has been granted access, the following endpoints will be active.

> Otherwise, these endpoints will return `404`. Check back for updates.

The Stripe Wallet rail provides USDC-based wallets on the Base blockchain with spending

via the x402 payment protocol. Your owner funds the wallet using Stripe's fiat-to-crypto

onramp (credit card → USDC), and you spend by requesting cryptographic payment signatures

that are settled on-chain.

How x402 Signing Works

When you encounter a service that returns HTTP `402 Payment Required` with x402 payment

details, you request a signature from CreditClaw:

1. You send the payment details to `POST /stripe-wallet/bot/sign`

2. CreditClaw enforces your owner's guardrails (per-tx limit, daily budget, monthly budget, domain allow/blocklist, approval threshold)

3. If approved, CreditClaw signs an EIP-712 `TransferWithAuthorization` message and returns an `X-PAYMENT` header

4. You retry your original request with the `X-PAYMENT` header attached

5. The facilitator verifies the signature and settles USDC on-chain

Request x402 Payment Signature

curl -X POST https://creditclaw.com/api/v1/stripe-wallet/bot/sign \
  -H "Authorization: Bearer $CREDITCLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource_url": "https://api.example.com/v1/data",
    "amount_usdc": 500000,
    "recipient_address": "0x1234...abcd"
  }'

**Request fields:**

| Field | Required | Description |

|-------|----------|-------------|

| `resource_url` | Yes | The x402 endpoint URL you're paying for |

| `amount_usdc` | Yes | Amount in micro-USDC (6 decimals). 1000000 = $1.00 |

| `recipient_address` | Yes | The merchant's 0x wallet address from the 402 response |

| `valid_before` | No | Unix timestamp for signature expiry |

**Response (approved — HTTP 200):**

{
  "x_payment_header": "eyJ0eXAiOi...",
  "signature": "0xabc123..."
}

Use the `x_payment_header` value as-is in your retry request:

curl https://api.example.com/v1/data \
  -H "X-PAYMENT: eyJ0eXAiOi..."

**Response (requires approval — HTTP 202):**

{
  "status": "awaiting_approval",
  "approval_id": 15
}

When you receive a 202, your owner has been notified. Poll the approvals endpoint

or wait approximately 5 minutes before retrying.

**Response (declined — HTTP 403):**

{
  "error": "Amount exceeds per-transaction limit",
  "max": 10.00
}

Other possible decline errors:

**Guardrail checks (in order):**

1. Wallet active? (not paused/frozen)

2. Amount ≤ per-transaction limit?

3. Daily cumulative + amount ≤ daily budget?

4. Monthly cumulative + amount ≤ monthly budget?

5. Domain on allowlist? (if allowlist is set)

6. Domain not on blocklist?

7. Amount below approval threshold? (if set)

8. Sufficient USDC balance?

Check Stripe Wallet Balance

curl "https://creditclaw.com/api/v1/stripe-wallet/balance?wallet_id=1" \
  -H "Authorization: Bearer $CREDITCLAW_API_KEY"

Response:

{
  "wallet_id": 1,
  "balance_usdc": 25000000,
  "balance_usd": "25.00",
  "status": "active",
  "chain": "base"
}

View Stripe Wallet Transactions

curl "https://creditclaw.com/api/v1/stripe-wallet/transactions?wallet_id=1&limit=10" \
  -H "Authorization: Bearer $CREDITCLAW_API_KEY"

**Transaction types:**

| Type | Meaning |

|------|---------|

| `deposit` | Owner funded the wallet via Stripe onramp (fiat → USDC) |

| `x402_payment` | You made an x402 payment |

| `refund` | A payment was refunded |

**Rate limit:** 30 requests per hour (signing), 12 requests per hour (balance/transactions).

---

API Reference

All endpoints require `Authorization: Bearer <api_key>` header (except register).

Base URL: `https://creditclaw.com/api/v1`

Core Endpoints

| Method | Endpoint | Description | Rate Limit |

|--------|----------|-------------|------------|

| POST | `/bots/register` | Register a new bot. Returns API key + claim token. | 3/hr per IP |

| GET | `/bot/wallet/check` | Lightweight heartbeat: balance, status, limits. | 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 |

Self-Hosted Card Endpoints (Rail 4)

| 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 |

Stripe Wallet Endpoints (Private Beta)

| 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 |

---

Error Responses

| 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}` |

---

Webhooks (Optional)

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.

---

Important Rules