PE Governor

First purchase walkthrough

The exact end-to-end flow for a buying agent’s first paid decision.

01

Two distinct sets of credentials

The seller holds Coinbase Business API credentials on the server, used only to create and read checkouts with view permission. They never leave the backend.

The buyer holds a wallet funded with USDC on Base and drives an x402 client. It is never shared with the seller. These are never the same key: the seller never holds buyer funds and never has custody, brokerage, or wallet control.

02

Step 1 — Request a decision (receive 402)

request.sh
curl -sS -X POST https://governor.solarly.ai/api/pe/v1/governor \
  -H 'content-type: application/json' \
  -H 'x-idempotency-key: 3f6d1a2e-9c40-4f1b-9c2a-6a5c1e0f7b21' \
  --data-binary @request.json

The first valid call reserves the logical request, creates exactly one Coinbase Business checkout (the same idempotency key is forwarded to Coinbase), and returns HTTP 402:

402.json
{
  "payment": {
    "provider": "coinbase_business",
    "protocol": "x402",
    "scheme": "auth-capture",
    "currency": "USDC",
    "network": "base",
    "amount": "1.00",
    "checkoutId": "0a1b2c3d4e5f60718293a4b5",
    "x402Url": "https://...",
    "settlementSource": "CHECKOUT_COMPLETED"
  }
}

No decision is included in a 402.

03

Step 2 — Pay the x402 URL

The buyer’s agent pays payment.x402Url with an x402 client wallet funded in USDC on Base. The authorization response from the x402 URL is not settlement — it only authorizes. Do not treat it as proof of payment.

04

Step 3 — Poll the same request

Retry with the same X-Idempotency-Key plus the issued X-Checkout-Id. The body may be omitted on retries.

retry.sh
curl -sS -X POST https://governor.solarly.ai/api/pe/v1/governor \
  -H 'x-idempotency-key: 3f6d1a2e-9c40-4f1b-9c2a-6a5c1e0f7b21' \
  -H 'x-checkout-id: 0a1b2c3d4e5f60718293a4b5'
  • Checkout ACTIVE or PROCESSING → HTTP 202 with a retry hint. Poll again with backoff.
  • Checkout COMPLETED with exactly matching amount, currency, and network → the request is marked PAID and HTTP 200 returns the stored pe-governor-decision.v1.
  • Terminal (failed, expired, cancelled) → structured 402 error.
  • Settled amount, currency, or network mismatch → 409 PAYMENT_MISMATCH, audited, never fulfilled.
  • Changed request body or a mismatched checkout id → 409.
05

Step 4 — Exact replay

Any further call with the same idempotency key returns the identical stored decision bytes, including the same decisionHash.

06

Credits alternative

Instead of a checkout, a caller may present a hashed bearer credit token. Consumption is a single atomic decrement under a row lock and is unique per request. A request that already has an attached Coinbase checkout can never switch to the credit path. Pricing is pay-per-decision or credits — there is no subscription.