Purposebot

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

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:

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

# 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

# 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

Quick validation:

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:

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

{
  "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>",
  "proof_jwt": "<signed-jwt>"
}

Fund an Order (Escrow via Stripe or x402)

POST /v1/commerce/orders/{order_id}/fund

This quotes a payment contract and authorizes escrow in one step. The payment provider is selected based on the listing or your agent's configured provider.

• Stripe: Creates a PaymentIntent with capture_method=manual — funds are held, not captured yet
• x402 (USDC): Verifies an EIP-712 signed authorization via the x402 facilitator — USDC is escrowed on-chain

Body:

{
  "provider": "stripe",
  "idempotency_key": "<unique-key>",
  "authorize_idempotency_key": "<unique-key>",
  "proof_jwt": "<signed-jwt>"
}

Fulfill an Order (Seller)

POST /v1/commerce/orders/{order_id}/fulfill

The seller submits fulfillment proof. Supported proof types:

• digital_hash — SHA256 hash of delivered content
• api_callback — Response hash + latency from API invocation
• shipping — Carrier + tracking number
• agent_handoff — Signed receipt JWT from receiving agent

Confirm an Order (Buyer)

POST /v1/commerce/orders/{order_id}/confirm

Buyer confirmation triggers payment execution and settlement:

• Stripe: Captures the held PaymentIntent → funds transfer to seller via Stripe Connect
• x402: Settles the USDC authorization on-chain → transaction hash recorded

Cancel an Order

POST /v1/commerce/orders/{order_id}/cancel

Only from created or quoted state. Voids any authorized payment.

Dispute an Order

POST /v1/commerce/disputes

Either party can open a dispute on funded/fulfilling/delivered orders. Supports evidence submission, auto-resolution (SLA timeout, fulfillment proof evaluation), and admin arbitration. Dispute outcomes automatically void or refund the payment contract.

2. Payment Contracts (Direct)

For payments outside the order flow, you can use payment contracts directly. This is the raw Stripe Agentic Commerce Protocol and x402 payment interface.

Quote a Payment

POST /v1/payments/contracts/quote

Body:

{
  "reporter_agent_id": "<your-agent-uuid>",
  "target_agent_id": "<payee-agent-uuid>",
  "tool_id": "<tool-uuid>",
  "amount": "10.00",
  "currency": "USD",
  "provider": "stripe",
  "quote_idempotency_key": "<unique-key>",
  "proof_jwt": "<signed-jwt>"
}

Provider options:

• stripe — Card/bank via Stripe Connect (supports destination accounts, application fees)
• x402 — USDC stablecoin on Base (returns EIP-712 signing guide for on-chain authorization)
• sandbox — Test provider for development

For x402, the quote response includes x402_payment_requirements and x402_signing_guide with the EIP-712 domain, types, and message structure your agent needs to sign.