Agent payments via x402 + USDC on Base

How it works

1. Agent makes a request to https://providersignal.com/api/v1/agent/<endpoint>
2. Server returns 402 Payment Required with PaymentRequirements in the body (price, network, receiving address, asset)
3. Agent signs a payment authorization with its USDC wallet and retries the request with an X-PAYMENT header
4. Coinbase's x402 facilitator verifies the signature, the receiver is paid in USDC, and the API returns the response in the citation envelope

We do not implement any custom payment flow. Any agent that already speaks the x402 protocol works with ProviderSignal out of the box.

Pricing

All prices are in USDC on Base (mainnet) or Base Sepolia (testnet). Atomic units are the canonical form to avoid float-rounding bugs in the verification path; USD figures are derived for display.

USDC has 6 decimals: 1 USDC = 1,000,000 atomic units. So $0.10 = 100,000 atomic, $2.50 = 2,500,000 atomic. The atomic value is what the x402 facilitator verifies on-chain.

Why per-call pricing varies. Basic-tier endpoints (lookup, search) are priced near commodity because the underlying data is largely derivable from public NPI. Moat-tier endpoints (DSO inference, scoring, territory rollup, license event history) encode work that takes months to replicate from raw sources, and are priced 10-25× basic.

Network & asset

• Production: Base mainnet (chain id eip155:8453), Circle USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913)
• Testnet: Base Sepolia (chain id eip155:84532), Circle USDC test token (0x036CbD53842c5426634e7929541eC2318f3dCF7e)
• Facilitator: https://x402.org/facilitator (testnet, no auth) or https://api.cdp.coinbase.com/platform/v2/x402 (mainnet, requires CDP project)
• Settlement: on-chain USDC transfer to ProviderSignal's receiving wallet. Gas is paid by the facilitator in most flows; agents only pay the per-call USDC amount.

Response shape

Paid endpoints return the same citation envelope as subscription endpoints. Differences appear only in meta.request:

{
  "data": { /* full provider record */ },
  "error": null,
  "meta": {
    "envelope_version": "1.0",
    "source_attribution": [
      { "table": "npi", "last_refresh": "2026-04-29T03:14:22Z",
        "schema_version": "v2", "license": "public-domain" }
    ],
    "confidence": {
      "provider_record": { "score": 87, "method": "completeness+multi_source", ... }
    },
    "request": {
      "id": "req_...",
      "endpoint": "/api/v1/agent/lookup-by-npi",
      "billed_credits": 1,
      "billing_method": "per_query"
    }
  }
}

Subscription consumers see the same envelope with billing_method: "subscription". The free tier returns a stripped envelope without confidence, with billing_method: "free".

Status codes

• 200 — payment verified, response in citation envelope
• 400 — request validation failed (e.g., malformed npi)
• 402 — no payment header, or payment did not satisfy the route's requirements. Body contains PaymentRequirements describing the price + asset.
• 404 — payment verified, but the requested resource (e.g., NPI) does not exist
• 503 — endpoint reserved but not yet implemented (Phase 3.5 territory rollup + license events)

When per-call vs subscription?

Per-call (this page) is the right path when:

• You're an agent that wants to evaluate quality before committing to subscription
• Your usage is bursty — a few hundred calls per month, not thousands
• You don't want to manage an API key or sign a contract
• Your buyer wants every call to be a discrete, billable transaction

Subscription pricing becomes more economical above ~$30/mo of per-call spend. The Rep tier ($149/mo) gives unlimited dashboard access + 500 req/min API throughput; agents that hit that threshold typically migrate via API key rather than continuing per-call.

References

• /openapi.json — full OpenAPI 3.1 spec with all endpoints + envelope schema
• /docs/fields — field-level glossary + stability guarantees
• /docs/free-tier — no-auth lookup endpoint for quality evaluation
• x402.org — protocol spec, facilitator endpoints, client SDKs