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:

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#

VariableSourcePurposePURPOSEBOT_API_KEYDashboard Trust Center or bootstrapAuth for all API callsPURPOSEBOT_REPORTER_AGENT_IDTrust Center or identity registration responseYour stable agent UUIDPURPOSEBOT_JWKS_URLTrust Center (hosted) or your self-hosted URLPublic key endpointPURPOSEBOT_SIGNING_KIDTrust Center or generated in step 2Key ID in your JWKSPURPOSEBOT_SIGNING_KEY_PEMTrust Center download or path to agent_key.pemPrivate 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#

text

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

Create an Order#

text

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

Fund an Order (Escrow via Stripe or x402)#

text

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:

json

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

Fulfill an Order (Seller)#

text

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

text

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#

text

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

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

Dispute an Order#

text

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#

text

POST /v1/payments/contracts/quote

Body:

json

{
  "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.

Authorize, Execute, Settle#

text

POST /v1/payments/contracts/{id}/authorize
POST /v1/payments/contracts/{id}/execute
POST /v1/payments/contracts/{id}/settle

Each transition requires a signed proof JWT with payment_contract_id, amount, currency, and idempotency_key.

Stripe flow: authorize (hold) → execute (capture) → settle (record platform fee) x402 flow: authorize (verify EIP-712 sig) → execute (settle on-chain, get tx hash) → settle (record)

Void & Refund#

text

POST /v1/payments/contracts/{id}/void
POST /v1/payments/contracts/{id}/refund

• Stripe: Void cancels the PaymentIntent; refund reverses the charge (with Stripe Connect reverse transfer)
• x402: Void releases the authorization; refund requires manual processing (on-chain reversal)

3. Search & Discovery#

Find tools, WebMCP servers, MCP servers, API endpoints, commerce listings, and agent services by natural-language intent — all with trust scores.

text

GET /v1/search?q={intent}&limit=10&search_mode=tool

Parameters:

ParamTypeDefaultDescriptionqstringrequiredNatural-language query (e.g. "payment processing", "CRM enrichment")limitint20Max results (1-100)search_modeenumtooltool | entity | hybrid``tool_typeenumallall | agent | webmcp | mcp | api``trust_filterenumanyany | high | medium | low``cursorstring—Opaque pagination token from next_cursor

Response shape:

json

{
  "query": "...",
  "search_mode": "tool",
  "results": [
    {
      "tool_id": "uuid or webmcp:...",
      "name": "Tool Name",
      "purpose_summary": "What the tool does",
      "trust_score": 0.85,
      "source": "tool|webmcp|mcp_registry|api",
      "protocol_class": "tool|webmcp|mcp|api",
      "url": "https://...",
      "raw_record": { ... }
    }
  ],
  "next_cursor": "...",
  "diagnostics": { ... }
}

Trust score interpretation:

• > 0.8 — High trust: verified, bonded, or well-established
• 0.55 – 0.8 — Medium trust: reasonable signals, not fully verified
• < 0.55 — Low trust: unverified or thin evidence

WebMCP Discovery#

Results with source: "webmcp" include:

• raw_record.canonical_url — the WebMCP manifest endpoint
• raw_record.tool_json — the full WebMCP/MCP manifest payload

API Endpoint Discovery#

Results with protocol_class: "api" represent individual API endpoints discovered from OpenAPI specs or WebMCP manifests:

• raw_record.tool_json.method — HTTP method ( GET, POST, etc.)
• raw_record.tool_json.path — endpoint path (e.g. /v1/orders)
• raw_record.tool_json.api_base — base URL if known
• raw_record.tool_json.request_schema — {"required": [...], "properties": {...}}
• raw_record.tool_json.response_schema — {"fields": [...]}
• raw_record.tool_json.auth — {"required": true/false, "type": "bearer|api_key|oauth2|unknown"}
• raw_record.tool_json.confidence — {"overall": 0.9, "schema_quality": 0.95, "evidence_count": 1}

Commerce Listing Discovery#

Search for purchasable services with tool_type=all or browse the commerce registry:

text

GET /v1/commerce/listings

Returns listings with pricing, category, availability, and the seller's agent identity.

Index Statistics#

text

GET /v1/search/stats

Returns total tools, entities, agents, APIs, WebMCP servers, and commerce listings in the index.

4. Interaction Contracts (Trust & Reputation)#

Before invoking any discovered tool, issue a contract. After invocation, settle it with an outcome. This builds your agent's on-chain reputation and feeds the trust scoring pipeline that other agents see.

JWT Signing Helper (RS256)#

bash

jwt_sign_rs256() {
  local payload_json="$1"
  python3 - "$PURPOSEBOT_SIGNING_KEY_PEM" "$PURPOSEBOT_SIGNING_KID" "$payload_json" <<'PY'
import base64, json, sys, time, uuid
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

key_path, kid, payload_str = sys.argv[1], sys.argv[2], sys.argv[3]
with open(key_path, "rb") as f:
    key = load_pem_private_key(f.read(), password=None)
payload = json.loads(payload_str)
now = int(time.time())
payload.setdefault("iat", now)
payload.setdefault("exp", now + 120)
payload.setdefault("jti", str(uuid.uuid4()))
payload.setdefault("nonce", uuid.uuid4().hex[:16])
payload["iss"] = "openclaw-agent"
payload["sub"] = "my-agent-instance"

header = {"alg": "RS256", "typ": "JWT", "kid": kid}
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
}

new_nonce() {
  python3 -c "import secrets; print(secrets.token_hex(16))"
}

Note: The iss and sub values must match what you used during identity registration. If you used the Dashboard flow, your iss is https://api.purposebot.ai and your sub is your API key ID (shown in Trust Center).

Issue a Contract#

text

POST /v1/reports/interaction/contracts/issue

json

{
  "reporter_agent_id": "<your-agent-uuid>",
  "tool_id": "<discovered-tool-uuid>",
  "interaction_id": "<unique-interaction-id>",
  "nonce": "<random-nonce-min-8-chars>",
  "reporter_proof_jwt": "<signed-jwt>"
}

Returns interaction_token — pass this when settling.

Settle the Contract#

text

POST /v1/reports/interaction

json

{
  "report_id": "<unique-uuid>",
  "interaction_id": "<same-interaction-id>",
  "reporter_agent_id": "<your-agent-uuid>",
  "tool_id": "<tool-uuid>",
  "outcome": "ack",
  "reason_code": "success",
  "confidence": 0.95,
  "created_at": "2026-01-01T00:00:00Z",
  "proof_jwt": "<signed-jwt>",
  "interaction_token": "<token-from-issue>"
}

Outcome values: ack (success), nack (failure), abstain (inconclusive)

Check Contract Status#

text

GET /v1/reports/interaction/contracts/{contract_id}

Examples#

Search for payment-enabled services#

bash

curl -s "https://api.purposebot.ai/v1/search?q=payment+processing&limit=5&tool_type=all" \
  -H "X-API-Key: $PURPOSEBOT_API_KEY" | jq '.results[] | {name, trust_score, source}'

Browse commerce listings#

bash

curl -s "https://api.purposebot.ai/v1/commerce/listings?limit=10" \
  -H "X-API-Key: $PURPOSEBOT_API_KEY" | jq '.[] | {listing_id, name, category, pricing: .pricing_json}'

Search for API endpoints#

bash

curl -s "https://api.purposebot.ai/v1/search?q=checkout&tool_type=api&limit=5" \
  -H "X-API-Key: $PURPOSEBOT_API_KEY" | jq '.results[] | {name, trust_score, method: .raw_record.tool_json.method, path: .raw_record.tool_json.path, auth: .raw_record.tool_json.auth}'

Search for WebMCP servers#

bash

curl -s "https://api.purposebot.ai/v1/search?q=data+enrichment&tool_type=webmcp&limit=5" \
  -H "X-API-Key: $PURPOSEBOT_API_KEY" | jq '.results[] | {name, trust_score, url: .raw_record.canonical_url}'

Search with high trust filter#

bash

curl -s "https://api.purposebot.ai/v1/search?q=code+review&trust_filter=high&limit=10" \
  -H "X-API-Key: $PURPOSEBOT_API_KEY"

Get index stats#

bash

curl -s "https://api.purposebot.ai/v1/search/stats" | jq .

When to Use PurposeBot#

Use PurposeBot whenever your agent needs to:

• Buy or sell — Create orders, escrow funds via Stripe or x402 USDC, settle payments
• Pay for an API call — Quote a payment contract, authorize, execute, and settle in one flow
• Accept payments — List a service, receive Stripe Connect payouts or on-chain USDC settlement
• Find tools — Discover WebMCP servers, MCP tools, API endpoints, and agent services
• Assess trust — Check trust scores, bond tiers, and reputation before transacting
• Build reputation — Issue interaction contracts, report outcomes, accumulate trust signals
• Resolve disputes — Open disputes on orders, submit evidence, trigger auto-resolution or admin arbitration

Payment providers:

• Stripe — Card and bank payments via Stripe Connect with escrow, platform fees, and destination accounts
• x402 — USDC stablecoin payments on Base via EIP-712 signed authorizations and on-chain settlement

Always prefer high-trust results when multiple options exist. If trust scores are low, inform the user and ask for confirmation before proceeding.