API

Agent payments, per call by USDC or card

Per-call payments for AI agents on two rails that share one 402: USDC via x402 on Base, or credit card via Stripe MPP. No API key, no signup, no minimum commitment. Full provider intelligence with citation provenance on every response.

See pricing tiersFree eval tier
How It WorksPay by CardPricingNetwork & AssetResponse ShapeStatus CodesWhen to UseReferencesFull API reference →

How it works

Two per-call rails share the same 402: USDC (x402, below) and credit card (MPP, in the next section). The USDC flow:

  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.

Pay by card (MPP)

Not every agent holds a USDC wallet. The same 402 also advertises a credit-card rail via Stripe's Machine Payments Protocol (MPP), so a card-capable agent can pay per call with no crypto.

  1. The 402 Payment Required carries an MPP challenge in the WWW-Authenticate header (method="stripe", the per-call price) alongside the x402 PaymentRequirements.
  2. The agent mints a Stripe Shared Payment Token (for example via @stripe/link-cli) and retries with an Authorization: Payment <token> header.
  3. The gateway verifies the token, charges the card, and returns the data in the same citation envelope plus a Payment-Receipt header.

Prices are identical on both rails. The $0.50 floor exists so every endpoint clears the card-network minimum. Pick whichever rail your wallet supports; the x402 (USDC) path is unchanged.

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.

EndpointTierUSDUSDC atomic
/api/v1/agent/lookup-by-npibasic$0.50500,000
/api/v1/agent/searchbasic$0.50500,000
/api/v1/agent/dso/affiliationmoat$1.001,000,000
/api/v1/agent/scoringmoat$1.001,000,000
/api/v1/agent/license/events/historicalmoat$1.501,500,000
/api/v1/agent/territory/rollupmoat$2.502,500,000
/api/v1/agent/market/positioningmoat$0.50500,000
/api/v1/agent/medicaid/ratesbasic$0.50500,000
/api/v1/free/lookupevalfree100/day
/api/v1/free/medicaid-ratesevalfree25/day
/api/v1/free/searchevalfree10/day
/api/v1/free/territoryevalfree10/day

USDC has 6 decimals: 1 USDC = 1,000,000 atomic units. So $0.50 = 500,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, market positioning) encode work that takes months to replicate from raw sources, and are priced 5-25x 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.

Onchain discovery (ERC-8257)

All eight paid endpoints are registered in the ERC-8257 Agent Tool Registry on Base, so onchain agents can discover, verify, and invoke them without any out-of-band setup: tool IDs 137-144 (market positioning, territory rollup, provider lookup, provider search, DSO affiliation, acquisition scoring, license events, Medicaid rates) at registry 0x265BB2DBFC0A8165C9A1941Eb1372F349baD2cf1. Each entry commits a keccak256 hash of its manifest, served from this origin at /.well-known/ai-tool/<slug>.json, with x402 pricing declared inline. Browse the registry on Agent Tool Index.

Response Shape

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

json
{ "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": 5, "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

CodeStatusDescription
200OKPayment verified, response in citation envelope.
400Bad RequestRequest validation failed (e.g., malformed npi).
402Payment RequiredNo payment, or payment did not satisfy the route's requirements. Advertises both per-call rails: x402 PaymentRequirements in the body + PAYMENT-REQUIRED header (USDC), and an MPP challenge in the WWW-Authenticate header (card).
404Not FoundPayment verified, but the requested resource (e.g., NPI) does not exist.
429Too Many RequestsRate limit exceeded at the sidecar layer (separate buckets for unpaid 402 traffic and paid traffic).

When per-call vs subscription?

Per-call (this page)

  • You're an agent that wants to evaluate quality before committing to a 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

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

See subscription pricing →

References

  • /openapi.json: full OpenAPI 3.1 spec with every endpoint and the envelope schema.
  • /docs/fields: field-level glossary plus stability guarantees.
  • /docs/free-tier: no-auth lookup endpoint for quality evaluation.
  • /api-docs: REST API for subscription consumers (auth, scopes, pagination, errors).
  • x402.org: protocol spec, facilitator endpoints, client SDKs (USDC rail).
  • paymentauth.org: the Machine Payments Protocol (MPP) spec behind the Stripe card rail.