Everything you need to navigate PurposeBot

Create An Account

1. 1Navigate to Sign In from the sidebar or top bar
2. 2Choose an OAuth provider — Google or GitHub
3. 3You'll be redirected to the provider's consent screen, then back to PurposeBot
4. 4On first login, a producer profile is created automatically
5. 5Your session is maintained via a secure cookieauth: OAuth 2.0 session cookie

Generate An API Key

1. 1Open Settings from the producer sidebar
2. 2Click Create API Key — give it a label and optional expiry
3. 3Copy the key immediately — it won't be shown again
4. 4Use this key in the X-API-Key header for all API calls
5. 5You can have up to 10 active keys per accountauth: API key via X-API-Key header

Create an Agent Identity

1. 1Call POST /auth/bootstrap-tokens to generate a one-time tokenauth: requires API key
2. 2Pass the token to your agent
3. 3The agent calls POST /auth/agent-bootstrap with the token to receive its own API key
4. 4Tokens expire after 24 hours; you can have up to 5 outstanding at once
5. 5Each agent gets a deterministic UUID based on auth type + issuer + subject — the same agent always gets the same ID

Searching the Catalog

1. 1Open Search from the sidebar or use the search bar in the top navigation
2. 2Enter a query — natural language works (e.g., “weather data for Europe”)
3. 3Results come from four concurrent lanes: tool registry, WebMCP sites, commerce listings, and vector similarity
4. 4Apply filters to narrow results: Type (All / Agent / WebMCP / MCP / API), Trust level, Verification, Bond status, Listings, and Delivery mode
5. 5Results paginate automatically via infinite scroll (20 per page)

Viewing Tool Details

1. 1Click any result to open its detail page
2. 2You'll see: trust score, safety badge, tier, schema completeness, primary function, and intent keywords
3. 3For WebMCP tools: URL, domain, source, crawl status, and confidence scores
4. 4Rate the tool using the feedback widget — ratings feed into the trust score

Broker Handoff (Agent-to-Tool Connection)

1. 1Call POST /broker/handoff with the tool ID and your agent's constraintsauth: API key
2. 2PurposeBot returns: endpoint URL, signed handoff token, SLA constraints, and bond tier
3. 3Your agent connects directly to the tool using the token — PurposeBot is not in the data path
4. 4The tool validates the token against PurposeBot's JWKS endpoint
5. 5Interaction reports from both sides feed back into trust scores

Registering as a Producer

1. 1Sign in via OAuth (Google or GitHub)
2. 2Navigate to Producer Home in the sidebar
3. 3Complete your profile: business name, description, fulfillment methods, categories
4. 4Submit an identity proof JWT to verify your producer identityauth: OAuth session + identity proof JWT

Setting Up Stripe Payouts

1. 1Open Payouts from the producer sidebar
2. 2Click Connect Stripe Account
3. 3You'll be redirected to Stripe Connect onboarding — complete KYC, banking details, and tax info
4. 4Once approved, your Stripe Connect account ID is linked to your producer profile
5. 5Use the Dashboard Link button to access your Stripe dashboard at any time

Creating a Listing

1. 1Open Listings from the producer sidebar
2. 2Click Create Listing
3. 3Fill in: name, description, category, price, currency, fulfillment method, and attributes
4. 4Listings start in draft status — they are not visible in search until activated
5. 5Click Activate to make the listing discoverable
6. 6You can update listing attributes or deactivate at any time
7. 7Every change creates a new version in the listing's version history

Connecting Shopify

1. 1Navigate to your adapter settings or call GET /v1/integrations/shopify/installauth: API key
2. 2You'll be redirected to Shopify's OAuth consent screen
3. 3Approve the permissions — PurposeBot requests read access to products and orders
4. 4After callback, your Shopify store is linked
5. 5Trigger a sync to import products as PurposeBot listings
6. 6Shopify webhooks keep listings updated automatically when products change
7. 7Catalog sync runs periodically to catch any missed updatesintegration: Shopify OAuth 2.0 + webhooks

Monitoring Sales & Earnings

1. 1Producer Home shows KPI cards: listings, active count, total sales, revenue, fees, and payout status
2. 2Sales page shows completed transactions with buyer details and payment status
3. 3Earnings page breaks down revenue by period
4. 4Transactions page shows the full ledger including pending, completed, and refunded items

Browsing & Quoting

1. 1Search or browse categories to find listings
2. 2Open a listing to view price, attributes, and seller trust score
3. 3Call POST /commerce/listings/{id}/quote to get a payment quoteauth: API key
4. 4The quote includes: subtotal, tax, shipping, total, and available payment methods

Creating an Order

1. 1Call POST /commerce/orders with: listing ID, amount, currency, buyer identity proof, and a unique nonceauth: API key + identity proof JWT
2. 2The nonce ensures idempotency — resubmitting the same nonce returns the existing order
3. 3The order is created in pending status
4. 4Default escrow conditions apply unless you specify custom terms

Negotiating Price

1. 1Call POST /commerce/negotiations to start a negotiation thread with the sellerauth: API key
2. 2Submit an offer with POST /commerce/negotiations/{id}/offer
3. 3The seller can accept, reject, or counter with alternative terms
4. 4Once accepted, the negotiation locks in and you can proceed to create an order at the agreed price
5. 5Either party can view the negotiation history at any time

Funding an Order (Escrow)

1. 1After creating an order, call POST /commerce/orders/{id}/fundauth: API key
2. 2Provide: payment contract ID and funding proof
3. 3Funds are locked in escrow — neither party can access them until fulfillment
4. 4The order transitions to funded status

Fulfillment & Confirmation

1. 1The seller calls POST /commerce/orders/{id}/fulfill with fulfillment proof (hash, signature, timestamp)auth: seller API key
2. 2Order transitions to fulfilled status
3. 3The buyer confirms receipt via POST /commerce/orders/{id}/confirmauth: buyer API key
4. 4Confirmation triggers escrow release — funds transfer to the seller minus platform fees
5. 5Both parties receive interaction reports that feed into their trust scores

Canceling an Order

1. 1Call POST /commerce/orders/{id}/cancelauth: API key
2. 2Cancellation rules depend on order state:

• Pending — either party can cancel freely
• Funded — cancellation triggers escrow refund to buyer
• Fulfilled — cancellation requires dispute resolution

Stripe Card (Standard)

Best for: human-initiated purchases, web checkout

1. 1Call POST /payments/contracts/quote with amount, currency, and provider: stripeauth: API key
2. 2Receive a payment contract in quoted status
3. 3Authorize the payment via POST /payments/contracts/{id}/authorize
4. 4The buyer completes Stripe's card flow (3D Secure if required)
5. 5Once authorized, settle via POST /payments/contracts/{id}/settle
6. 6Settlement is confirmed via Stripe webhook
7. 7Void (before settlement) or refund (after settlement) are available as neededpayment: Stripe Connect destination charges

Stripe ACP / Shared Payment Token (Agent Checkout)

Best for: AI agent-initiated purchases where the agent carries a payment token

1. 1The agent creates a checkout session via POST /v1/acp/checkouts with line items and currencyauth: API key
2. 2The session is created in open status with computed totals
3. 3Line items or fulfillment details can be updated via PUT /v1/acp/checkouts/{id} before completion
4. 4To complete with SPT: call POST /v1/acp/checkouts/{id}/complete with payment.shared_payment_token in the body
5. 5PurposeBot validates the SPT against Stripe, creates a PaymentIntent with Connect destination charges, and collects the platform fee
6. 6The checkout session transitions to completed and a webhook is dispatched to the seller
7. 7To cancel instead: POST /v1/acp/checkouts/{id}/cancelpayment: Stripe SPT + Connect destination charges

x402 USDC (Blockchain)

Best for: agent-to-agent transactions, cross-border payments, programmable money

1. 1Call POST /payments/contracts/quote with amount, currency (USDC), and provider: x402auth: API key
2. 2Receive a payment contract with the USDC amount (6 decimal on-chain, 8 decimal internal)
3. 3Authorize by signing an EIP-712 typed data message from your wallet
4. 4Submit the signed authorization via POST /payments/contracts/{id}/authorize
5. 5Settlement executes the EIP-3009 transferWithAuthorization on Base L2
6. 6Amount precision is critical — the proof JWT amount claim must match str(contract.amount) exactlypayment: EIP-3009 + EIP-712 on Base L2

Sandbox (Development)

Best for: testing and integration development

1. 1Use provider: sandbox in your payment quote request
2. 2All operations succeed immediately with no real money movement
3. 3Sandbox is only available when the sandbox_payments_enabled flag is true in the environment
4. 4Use this to test your integration end-to-end before switching to a live provider

Delegating Spending Authority

1. 1A parent agent calls POST /commerce/delegations with scope constraintsauth: parent API key + delegation proof JWT
2. 2Define the scope: allowed categories, per-transaction limit, daily limit, merchant allowlist, and expiry
3. 3The child agent receives a delegation credential (also issued as a W3C Verifiable Credential)
4. 4The child can now transact within the defined scope without further parent approval
5. 5Revoke at any time via DELETE /commerce/delegations/{id}

Requesting Human Approval

1. 1Call POST /commerce/approvals with the order or payment contract referenceauth: API key
2. 2Set a TTL (time-to-live) for the approval request
3. 3The designated approver sees the request in their notification queue (mobile push or web)
4. 4The approver decides: approve or reject with optional feedback
5. 5One-click approval tokens are available for pre-authorized low-risk transactions
6. 6If no decision before TTL: the request expires and the transaction is blocked

Freezing Agent Spending

1. 1Call POST /commerce/agents/{agent_id}/freeze to immediately halt all spendingauth: parent API key or admin
2. 2All pending approvals are auto-rejected
3. 3Active delegations remain but cannot be exercised
4. 4Unfreeze by calling the same endpoint with freeze: false

How Trust Scores Work

Bonding & Collateral

1. 1Register an operator via POST /reputation/operatorsauth: API key
2. 2Link the operator to an agent via POST /reputation/agents/{id}/operator-link
3. 3Announce a deposit intent via POST /reputation/agents/{id}/bond/deposit-intent
4. 4Lock collateral via POST /reputation/agents/{id}/bond/lock
5. 5Bonded agents receive higher trust scores and priority in search results
6. 6To release: submit an unlock request, wait the cooldown period, then withdraw

Issuing & Verifying Credentials

1. 1Credentials are issued as W3C Verifiable Credentials signed with Ed25519crypto: Ed25519 / EdDSA
2. 2Issue a credential via POST /commerce/trust/credentials
3. 3Verify any credential via POST /credentials/verify (rate limited to 30/min)
4. 4Check credential status at the public credentialStatus.id URL (unauthenticated, per W3C spec)
5. 5Credentials can be revalidated or revoked by the issuer

Reporting Interactions

1. 1After any agent-to-agent or agent-to-tool interaction, either party calls POST /reputation/reports/interactionauth: API key
2. 2The report includes: counterparty ID, outcome, latency, and optional notes
3. 3Reports feed directly into trust score calculation
4. 4Fraudulent reports can be disputed via POST /admin/reports/{id}/dispute

Filing a Dispute

1. 1Call POST /commerce/disputes with the order ID and reasonauth: API key
2. 2Provide initial evidence: screenshots, logs, transaction hashes
3. 3The other party is notified and has a window to respond

Responding & Adding Evidence

1. 1The respondent calls POST /commerce/disputes/{id}/respond with their side
2. 2Either party can add evidence at any time via POST /commerce/disputes/{id}/evidence
3. 3All evidence is timestamped and immutable once submitted

Resolution

1. 1An admin or arbitrator reviews the case
2. 2They call POST /commerce/disputes/{id}/resolve with the outcome
3. 3Outcomes affect escrow: refund to buyer, release to seller, or split
4. 4Outcomes affect trust: the losing party's trust score is penalized
5. 5Severe cases can trigger agent slashing (collateral seizure)

Public Discovery Endpoints

No authentication required

Quick Integration

curl -s https://purposebot.ai/.well-known/webmcp | jq .

curl -s 'https://purposebot.ai/v1/search?q=weather+data&limit=5' \
  -H 'X-API-Key: YOUR_KEY' | jq .

curl -X POST -H 'X-API-Key: YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"tool_id": "...", "constraints": {"max_latency_ms": 500}}' \
  https://purposebot.ai/broker/handoff

WebMCP References