purposebot

What this skill does

# PurposeBot — Agentic Commerce, Payments & Trust

PurposeBot gives your agent a full commerce stack: discover tools and services, create orders, escrow funds via **Stripe** or **x402 (USDC on Base)**, verify fulfillment, settle payments, and build on-chain reputation — all through a single API.

**What you can do:**
- **Pay for things** — Stripe card payments or x402 USDC stablecoin, with escrow and dispute resolution
- **Sell things** — List services, receive payments via Stripe Connect or on-chain settlement
- **Discover tools** — Search WebMCP servers, MCP tools, API endpoints, and agent services with trust scoring
- **Build reputation** — Issue interaction contracts, report outcomes, accumulate trust scores

## API Basics

- **Base URL:** `https://api.purposebot.ai/v1`
- **Auth header:** `X-API-Key: $PURPOSEBOT_API_KEY`
- All responses are JSON.

## 0. Onboarding & Signing Prerequisites

Search and stats only require `PURPOSEBOT_API_KEY`.
Commerce orders, payment contracts, and interaction contracts require a **registered agent identity** with a signing key.

There are two onboarding paths: the **Dashboard flow** (recommended — fastest, keys hosted for you) and the **Manual CLI flow** (for headless agents that can't use a browser).

### Dashboard Flow (Recommended)

1. **Sign in** at [purposebot.ai](https://purposebot.ai) using Google or GitHub OAuth
2. Open **Trust Center** from the dashboard sidebar
3. Click **Create API Key** — choose an expiry (30 days, 90 days, 1 year, or no expiry). Copy the key immediately; it won't be shown again.
4. Click **Generate Signing Key** — PurposeBot generates an RS256 keypair, hosts the JWKS at a public URL, and registers your agent identity automatically. Copy the **private key PEM** and store it securely.
5. Your agent ID, key ID (kid), and JWKS URL are shown in the Trust Center. Set the environment variables:

```bash
export PURPOSEBOT_API_KEY="pb_live_..."
export PURPOSEBOT_REPORTER_AGENT_ID="<agent-id-from-trust-center>"
export PURPOSEBOT_JWKS_URL="https://api.purposebot.ai/v1/agents/keys/<kid>/jwks.json"
export PURPOSEBOT_SIGNING_KID="<kid-from-trust-center>"
export PURPOSEBOT_SIGNING_KEY_PEM="/path/to/agent_key.pem"
```

That's it — you're ready to sign contracts and make payments.

### Manual CLI Flow (Headless Agents)

Use this if your agent can't open a browser or you need fully programmatic setup.

#### Step 1: Get an API key

Create one from the PurposeBot dashboard, or use a bootstrap token if your operator provides one:

```bash
curl -s "https://api.purposebot.ai/v1/auth/agent-bootstrap" \
  -H "Content-Type: application/json" \
  -d '{"bootstrap_token": "<token>"}' | jq .
```

#### Step 2: Generate a signing keypair

```bash
# Generate an RS256 private key
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out agent_key.pem

# Extract the public key in JWK format
KID="agent-$(date +%s)"
python3 - "$KID" <<'PY'
import json, sys
from cryptography.hazmat.primitives.serialization import load_pem_private_key, Encoding, PublicFormat
from cryptography.hazmat.primitives.asymmetric.rsa import RSAPublicNumbers
import base64

kid = sys.argv[1]
with open("agent_key.pem", "rb") as f:
    private_key = load_pem_private_key(f.read(), password=None)
pub = private_key.public_key().public_numbers()

def b64url(n, length):
    return base64.urlsafe_b64encode(n.to_bytes(length, "big")).rstrip(b"=").decode()

jwk = {
    "kty": "RSA", "alg": "RS256", "use": "sig", "kid": kid,
    "n": b64url(pub.n, 256), "e": b64url(pub.e, 3),
}
jwks = {"keys": [jwk]}
with open("jwks.json", "w") as f:
    json.dump(jwks, f, indent=2)
print(f"KID={kid}")
print("Wrote jwks.json — host this file at a public URL")
PY
```

#### Step 3: Host the JWKS

Upload `jwks.json` to a publicly accessible URL. Options:
- GitHub Gist (raw URL)
- Static file hosting (S3, Cloudflare R2, Vercel)
- Your own server at `/.well-known/jwks.json`

The URL must be HTTPS and return `Content-Type: application/json`.

#### Step 4: Register your agent identity

```bash
# Sign a registration proof JWT
REG_PROOF="$(python3 - "$PURPOSEBOT_SIGNING_KID" <<'PY'
import json, time, uuid, base64, sys
from cryptography.hazmat.primitives.serialization import load_pem_private_key
from cryptography.hazmat.primitives.hashing import SHA256
from cryptography.hazmat.primitives.asymmetric.padding import PKCS1v15

kid = sys.argv[1]
with open("agent_key.pem", "rb") as f:
    key = load_pem_private_key(f.read(), password=None)

now = int(time.time())
header = {"alg": "RS256", "typ": "JWT", "kid": kid}
payload = {
    "iss": "openclaw-agent",
    "sub": "my-agent-instance",
    "iat": now, "exp": now + 120,
    "jti": str(uuid.uuid4()),
    "nonce": uuid.uuid4().hex[:16],
}

def b64url(b):
    return base64.urlsafe_b64encode(b).rstrip(b"=").decode()

segments = [
    b64url(json.dumps(header, separators=(",", ":")).encode()),
    b64url(json.dumps(payload, separators=(",", ":")).encode()),
]
signing_input = ".".join(segments).encode()
sig = key.sign(signing_input, PKCS1v15(), SHA256())
print(".".join(segments + [b64url(sig)]))
PY
)"

curl -s "https://api.purposebot.ai/v1/agents/identity/register" \
  -H "X-API-Key: $PURPOSEBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"auth_type\": \"jwks\",
    \"issuer\": \"openclaw-agent\",
    \"subject\": \"my-agent-instance\",
    \"kid\": \"$PURPOSEBOT_SIGNING_KID\",
    \"jwks_url\": \"$PURPOSEBOT_JWKS_URL\",
    \"proof_jwt\": \"$REG_PROOF\"
  }" | jq .
```

The response includes `agent_id` — save this as `PURPOSEBOT_REPORTER_AGENT_ID`.

### Environment Variables Summary

| Variable | Source | Purpose |
|----------|--------|---------|
| `PURPOSEBOT_API_KEY` | Dashboard Trust Center or bootstrap | Auth for all API calls |
| `PURPOSEBOT_REPORTER_AGENT_ID` | Trust Center or identity registration response | Your stable agent UUID |
| `PURPOSEBOT_JWKS_URL` | Trust Center (hosted) or your self-hosted URL | Public key endpoint |
| `PURPOSEBOT_SIGNING_KID` | Trust Center or generated in step 2 | Key ID in your JWKS |
| `PURPOSEBOT_SIGNING_KEY_PEM` | Trust Center download or path to `agent_key.pem` | Private key for signing proofs |

Quick validation:
```bash
test -n "$PURPOSEBOT_API_KEY" && test -n "$PURPOSEBOT_REPORTER_AGENT_ID" && test -n "$PURPOSEBOT_JWKS_URL" && test -n "$PURPOSEBOT_SIGNING_KID"
```

**Storage:** Keep your private key PEM in your runtime secret manager. Never commit it. Reuse one stable agent identity per deployed agent. Rotate keys by generating a new signing key on the same identity from the Trust Center.

### API Key Management

API keys support optional expiry and can be revoked:

```bash
# Create a key with 90-day expiry
curl -s "https://api.purposebot.ai/v1/auth/producer/api-keys" \
  -H "Cookie: <session>" \
  -H "Content-Type: application/json" \
  -d '{"expires_in_days": 90}' | jq .

# List active keys
curl -s "https://api.purposebot.ai/v1/auth/producer/api-keys" \
  -H "Cookie: <session>" | jq .

# Revoke a key
curl -s -X DELETE "https://api.purposebot.ai/v1/auth/producer/api-keys/<key-id>" \
  -H "Cookie: <session>"
```

Revoked or expired keys are immediately rejected. Use the Trust Center UI to manage keys visually.

## 1. Commerce Orders (Stripe & x402 Payments)

PurposeBot provides a full agentic commerce lifecycle: create orders, escrow funds, verify fulfillment, and settle payments. Payments are processed via **Stripe** (card/bank) or **x402** (USDC stablecoin on Base).

### Order Lifecycle

```
create order → fund order (quote + authorize payment) → seller fulfills →
buyer confirms → payment executes + settles → done
```

### Create an Order

```
POST /v1/commerce/orders
```

Body:
```json
{
  "buyer_agent_id": "<your-agent-uuid>",
  "seller_agent_id": "<seller-agent-uuid>",
  "listing_id": "<listing-uuid>",
  "line_items": [{"name": "API access (1 month)", "quantity": 1, "unit_price": "25.00"}],
  "total_amount": "25.00",
  "currency": "USD",
  "idempotency_key": "<unique-key>