Overview

Agent endpoints are mounted under /agents/v2/* and gated by x402 middleware using exact USDC payments.

Quickstart

1. Call endpoint normally — you will receive 402 with a payment-required header.
2. Use an x402 client to sign the payment payload with a funded Base mainnet USDC wallet.
3. Retry the same request through the x402-aware client — you will receive 200.

Python Example

import os
import requests
from eth_account import Account

from x402.client import x402ClientSync
from x402.http.clients.requests import wrapRequestsWithPayment
from x402.mechanisms.evm.signers import EthAccountSigner
from x402.mechanisms.evm.exact.client import ExactEvmScheme

base_url = "https://api.punkpredictor.xyz"

# Never hardcode private keys. Use a funded Base-mainnet wallet with USDC.
account = Account.from_key(os.environ["EVM_PRIVATE_KEY"])

client = x402ClientSync()
client.register("eip155:8453", ExactEvmScheme(EthAccountSigner(account)))

session = wrapRequestsWithPayment(requests.Session(), client)

r = session.post(
    f"{base_url}/agents/v2/fair-price",
    json={"id_punk": 9999},
    timeout=90,
)
print(r.status_code, r.json())

Endpoint Reference

Parameters

• fair-price and fair-price-plus: JSON body {"id_punk": <int>}
• for-sale: optional queries limit (default 100, max 1000) and offset (default 0)
• top-delayed and top-realtime: optional query limit (default 10, max 100)

Response Contracts

POST /agents/v2/fair-price

{
  "id_punk": 24,
  "fair_price_eth": 36.35,
  "pricing": { "usdc": "5.00" },
  "network": "eip155:8453",
  "x402_scheme": "exact"
}

POST /agents/v2/fair-price-plus

{
  "id_punk": 24,
  "fair_price_eth": 36.35,
  "distribution_of_possible_valuations": { "type": "ensemble", "summary": { "...": "..." } },
  "uncertainty_score": 0.11,
  "intervals": { "80": { "lower": 30.2, "upper": 41.9 } },
  "pricing": { "usdc": "10.00" },
  "network": "eip155:8453",
  "x402_scheme": "exact"
}

GET /agents/v2/for-sale

{
  "mode": "for_sale",
  "count": 1,
  "total": 1,
  "limit": 100,
  "offset": 0,
  "next_offset": null,
  "results": [
    {
      "id_punk": 5822,
      "listed_price_eth": 26.0,
      "source": "blur"
    }
  ],
  "pricing": { "usdc": "0.10" },
  "network": "eip155:8453",
  "x402_scheme": "exact"
}

GET /agents/v2/top-delayed & /top-realtime

{
  "mode": "realtime",
  "as_of_utc": "2026-02-12T22:29:05.100000+00:00",
  "count": 3,
  "results": [
    {
      "id_punk": 5730,
      "listed_price_eth": 35.0,
      "fair_price_eth": 39.1,
      "potential_upside_eth": 4.1,
      "discount_to_fair_pct": 10.49,
      "source": "blur"
    }
  ],
  "pricing": { "usdc": "50.00" },
  "network": "eip155:8453",
  "x402_scheme": "exact"
}

Errors & Refusals

Pricing

Prices are fixed per endpoint (USDC on Base mainnet):

Verifying Payment

Every successful call settles an on-chain USDC transfer to punkpredictor.eth. Your x402 client should also expose the settlement receipt returned in the payment-response (or x-payment-response) header.

# After a paid 200 response:
# - Parse tx hash from the payment-response header
# - Verify it on Basescan

Integration Checklist

1. Call an endpoint and handle the 402 payment challenge.
2. Sign and retry via an x402-aware client.
3. Confirm you receive 200 and a JSON response.
4. Extract the settlement tx hash from payment-response and verify it on Basescan.