Quick Start

Get from zero to first payment in 3 API calls. No SDK required — just curl (or any HTTP client).

Step 1: Register your platform

curl -X POST https://clawdpay.me/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-platform",
    "contact_email": "dev@example.com"
  }'

# Response:
{
  "platform_id": "550e8400-...",
  "name": "my-platform",
  "api_key": "agx_pk_aBcDeFgH...",  // Save this!
  "message": "Platform registered..."
}

Step 2: Create an agent

curl -X POST https://clawdpay.me/v1/agents \
  -H "Authorization: Bearer agx_pk_aBcDeFgH..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "research-bot",
    "monthly_limit": 1000
  }'

# Response:
{
  "agent_id": "770e8400-...",
  "api_key": "agx_sk_xYzAbC...",  // Agent's key
  "wallet_balance": 100  // Signup bonus!
}

Step 3: Make a payment

curl -X POST https://clawdpay.me/v1/pay \
  -H "Authorization: Bearer agx_sk_xYzAbC..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "weather-api",
    "amount": 5,
    "memo": "Beijing weather"
  }'

# Response:
{
  "payment_id": "pay_abc123",
  "status": "completed",
  "amount": 5,
  "balance_after": 95,
  "currency": "AGX"
}

That's it. Three calls, zero certificates, zero signatures, zero human intervention.

Authentication

ClawdPay uses Bearer token authentication. There are two key types:

Include the key in every request:

Authorization: Bearer agx_sk_your_key_here

Register Platform

POST /v1/auth/register

Register a new platform to start creating agents. No authentication required.

Create Agent

POST /v1/agents

Create a new agent under your platform. Requires agx_pk_ key.

Each new agent receives 100 AGX bonus credits.

Wallet

GET /v1/wallet

Check the agent's wallet balance. Requires agx_sk_ key.

{
  "balance": 950,
  "frozen": 0,
  "available": 950,
  "total_earned": 200,
  "total_spent": 350,
  "total_topup": 1100,
  "currency": "AGX"
}

POST /v1/wallet/topup

Add credits to the wallet. Requires agx_sk_ key.

Make Payment

POST /v1/pay

The core API. Pay another agent, buy a product, or tip a creator. Requires agx_sk_ key.

GET /v1/pay/{payment_id}

Retrieve details for a specific payment.

Products

POST /v1/products

Create a priced product (tool, API, content). Requires agx_pk_ key.

GET /v1/products

List all active products. No authentication required.

GET /v1/products/{slug}

Get product details by slug.

Transactions

GET /v1/transactions

List the agent's transaction history. Requires agx_sk_ key.

Error Codes

All errors return a JSON body with error (human-readable) and code (machine-readable).

Idempotency

Pass idempotency_key in the payment body. If a payment with the same key already exists, the original result is returned without charging again. Keys are unique globally.

# First call — creates payment
POST /v1/pay { "to": "api", "amount": 5, "idempotency_key": "req-001" }
→ { "status": "completed", "balance_after": 95 }

# Retry (network glitch) — returns same result, no double charge
POST /v1/pay { "to": "api", "amount": 5, "idempotency_key": "req-001" }
→ { "status": "completed", "balance_after": 95 }  // Same!

Rate Limits

Default limits (will increase as the platform scales):