# From a working x402 API to a Pyrimid-listed paid tool

This guide uses Bounty Truth API as a live, reproducible example. The current
endpoint already charges USDC on Base through the standard x402 HTTP flow.
Pyrimid can add catalog discovery and affiliate-aware routing without moving
the service to a different host.

## 1. Reproduce the unpaid request

Run:

~~~bash
curl -i \
  'https://happybirthday.digitalshop.xin/bounty-truth/api/v1/check?url=https%3A%2F%2Fgithub.com%2Fmadalynerlge2%2Fchi%2Fissues%2F1'
~~~

Agents that prefer JSON can request the same paid resource with:

~~~bash
curl -i -X POST \
  -H 'content-type: application/json' \
  --data '{"url":"https://github.com/madalynerlge2/chi/issues/1"}' \
  'https://happybirthday.digitalshop.xin/bounty-truth/api/v1/check'
~~~

The live service responds:

~~~http
HTTP/1.1 402 Payment Required
Content-Type: application/json; charset=utf-8
PAYMENT-REQUIRED: <base64-encoded x402 v2 payment requirements>

{}
~~~

Decode the PAYMENT-REQUIRED header as base64 JSON. Its accepted payment entry
identifies Base mainnet (eip155:8453), Base USDC, a price of 1000 atomic units
($0.001), and the vendor receiving address. Do not copy an encoded header from
this guide: fetch a fresh one so the resource URL and timeout are current.

The free machine-readable contract is:

~~~text
https://happybirthday.digitalshop.xin/bounty-truth/openapi.json
~~~

## 2. Define catalog metadata

This is the minimal metadata for the existing service. price_usdc uses USDC
atomic units, so 1000 means $0.001.

~~~json
{
  "vendor_id": "bounty-truth",
  "product_id": "github_bounty_check",
  "description": "Evidence-backed go/no-go assessment for a public GitHub bounty issue",
  "category": "developer-tools",
  "tags": ["github", "bounties", "risk", "x402", "paid-tools"],
  "price_usdc": 1000,
  "affiliate_bps": 2000,
  "endpoint": "https://happybirthday.digitalshop.xin/bounty-truth/api/v1/check",
  "network": "base",
  "asset": "USDC"
}
~~~

The public endpoint accepts the issue URL either as a GET query parameter named
url or as the url field in a POST JSON object. It must be a public GitHub issue
URL in the form https://github.com/owner/repository/issues/123.

## 3. Register and list through Pyrimid

Follow the current vendor instructions at:

https://pyrimid.ai/quickstart

The required onchain sequence is:

1. Call PyrimidRegistry.registerVendor with the service name, base URL, and
   payout address.
2. Call PyrimidCatalog.listProduct with the resulting vendor ID, product ID,
   endpoint, description, atomic USDC price, and affiliate share.
3. Gate the endpoint with the Pyrimid SDK or validate the Router payment proof
   before returning the paid result.
4. Have the buyer approve Base USDC and call PyrimidRouter.routePayment.
5. Retry the same HTTP request with the returned payment proof.

Never mark the integration complete merely because the metadata was accepted.
Verify all five observable outcomes from the Pyrimid quickstart: the product is
in the catalog, PaymentRouted exists on Base, protocol stats increment, the
vendor receives USDC, and the treasury receives its fee.

## 4. Keep the free and paid surfaces separate

The health check and OpenAPI contract stay free:

~~~text
GET https://happybirthday.digitalshop.xin/bounty-truth/health
GET https://happybirthday.digitalshop.xin/bounty-truth/openapi.json
~~~

Only the assessment route is paid. This lets a buyer agent discover the input
schema and price without spending money, then decide whether the paid result is
worth buying.

## 5. Production verification checklist

- An unpaid request returns 402 before any GitHub API work is performed.
- PAYMENT-REQUIRED names Base mainnet, Base USDC, the exact price, and the
  intended receiving address.
- A paid retry returns JSON matching the free OpenAPI schema.
- The catalog price equals the endpoint price; atomic units are not confused
  with decimal USDC.
- A real non-self purchase produces an onchain payment receipt and a successful
  service response.
- Logs never expose wallet private keys, API tokens, or raw payment proofs.

The last item is the real acceptance gate: a self-payment can test plumbing,
but it does not prove customer demand or revenue.