Become a provider

This page is not the way to start. It documents the partner-bridge route, which needs a repository you do not have access to and a registry entry only we can add. If you are here to charge AI agents for your own API or site, use the self-serve path below — you never need us, and it takes about five minutes.

Start here instead

Everything below is self-serve at dash.aifinpay.io — no repository, no approval, no contract:

Create an account and a service.
Give it a payout address (a standard 0x… EVM address; settlement is on Polygon today).
On Site settings, add a gateway: pick a slug and enter your upstream URL. Your paid endpoint is https://gateway.aifinpay.io/{your-slug}/… — that is the URL you hand to agents. It starts forwarding once the upstream’s domain is verified: add the TXT record _aifp-verify.<upstream-host> that Site settings shows under Domain verification. Until then it answers 403 gateway_unavailable.
Lock your origin so agents cannot bypass the paywall. Read Hosted Gateway before you do — the rule differs for an API and for a site with human readers, and using the API rule on a website will 403 your readers and drop you out of search.
Verify your domain: set Site URL under Profile & keys, then add the TXT record that the DNS connection queue on the account Dashboard shows for it. Agents using the AiFinPay MCP server do not pay until the domain is verified.

That is the whole thing. Hosted Gateway walks through it with no code at all; self-hosted verification is the alternative if you would rather keep traffic on your own domain and verify receipts yourself.

The partner-bridge route (requires us)

The rest of this page covers standing a thin x402 bridge in front of an API and listing it in the AiFinPay provider registry. It needs a pull request to a private repository and a registry entry we add by hand, so it is only relevant if you have already spoken to us about a registry listing. It is not a self-service path and should not be attempted as one.

Config-only

Front any JSON HTTP API by editing a .env file. No bridge code to fork or maintain — the generic bridge is fully env-driven.

Non-custodial & token-free

Per-call revenue settles straight to a wallet you own. No token to buy, no contract to sign, no KYC, no revenue-share bookkeeping.

What you need

Item	Why
A `0x` Polygon address (EOA or Safe)	Where your per-call revenue lands. Use a Safe for production — once funded, you own that wallet, not AiFinPay.
Your upstream API key	The bridge uses your key when forwarding paid requests. You set it as an env var on your own host; AiFinPay never sees it.
A box to run the bridge	A ~50 LoC Node service. Runs on a small VPS or any container platform.
A per-call price	What you charge agents per call, set in USD when you scaffold.

You do not need crypto integration in your existing stack, a wallet for your end users (your customers are AI agents that bring their own keypair via the AiFinPay SDK), or a compliance/KYC process — settlement is non-custodial and happens on-chain in the splitter contract.

Fast path — config only, no code

If your upstream is a normal JSON HTTP API, use the env-driven _generic-x402-bridge and scaffold a config in one command. No bridge code is written or edited.

Scaffold a provider config

Run scripts/new-provider.mjs with your three knobs and identity flags:

node scripts/new-provider.mjs \
  --slug mybrand --name "MyBrand AI" --category inference \
  --upstream-url https://api.mybrand.example/v1/chat/completions \
  --auth-style bearer --route-path /chat/completions --price-usd 0.02

This writes examples/mybrand-x402-bridge/.env and examples/mybrand-x402-bridge/README.md, and prints the services.json registry entry to paste. The script derives PRICE_WEI (native POL) and PRICE_USDC_UNITS / PRICE_USDT_UNITS (6-decimal stables) from your --price-usd.

Add your upstream API key

Open the generated .env and fill in the one secret the scaffold leaves blank:

UPSTREAM_API_KEY=sk-your-upstream-key

Optionally set BRIDGE_MERCHANT_WALLET to your own payout wallet — by default the scaffold points it at the AiFinPay treasury Safe.

Run the generic bridge with your config

The bridge code lives in _generic-x402-bridge; you point it at your scaffolded .env:

cd examples/_generic-x402-bridge && npm install
node --env-file=../mybrand-x402-bridge/.env server.js

Put it behind nginx / Caddy / fly.io / Railway / wherever — it’s a plain HTTP service, no special infra.

Paste the printed registry entry into oracle-financial-hub-59/backend/services.json. Once your bridge answers GET /.well-known/x402.json, the provider pinger marks it live and it becomes auto-selectable via /api/registry/best.

A manual fork path exists for upstreams that need custom request shaping, but the config-only path above is recommended for any standard JSON API.

The three knobs

Everything provider-specific is one of three env vars. The 402 challenge, on-chain verification, replay protection, rate limiting, and splitter integration are identical for every provider.

Knob	Env var	What it does
Upstream URL	`UPSTREAM_URL`	Where the bridge forwards the paid request.
Auth style	`UPSTREAM_AUTH_STYLE`	How the bridge authenticates to your upstream.
Price	`PRICE_WEI` / `PRICE_USDC_UNITS` / `PRICE_USDT_UNITS`	What the agent pays per call (derived from `--price-usd`).

Auth styles

UPSTREAM_AUTH_STYLE selects how UPSTREAM_API_KEY is attached when forwarding:

Value	Header sent to upstream	Typical upstreams
`bearer` (default)	`Authorization: Bearer <key>`	OpenAI, Venice, Tavily
`x-api-key`	`x-api-key: <key>`	Exa
`header`	`<UPSTREAM_AUTH_HEADER>: <key>`	ElevenLabs (`UPSTREAM_AUTH_HEADER=xi-api-key`)

Optional knobs

ROUTE_PATH=/chat/completions   # path this bridge exposes and forwards
REQUIRE_BODY_FIELD=messages    # reject JSON bodies missing this field (optional)
PORT=3000                      # bridge listen port

The on-chain split

AIFP-1 settles one quoted gross amount through a verified B2BSplitter v1.3 route:

payer total = quoted gross
                     ├──── 99% ────▶ merchant wallet
                     ├────  1% ────▶ AiFinPay treasury
                     └────  0% ────▶ creator/referral

The fee is not added on top. AIFP-2/x402 is a separate route with a current 0% AiFinPay protocol fee; the provider receives 100% and network gas is separate. A contract address or historical transaction is not sufficient readiness evidence. The bridge must remain fail-closed until its exact v1.3 address, runtime hash, on-chain BPS profile, merchant target, asset metadata and paid E2E evidence are pinned for the release. Historical v1.1/v1.2 payMatic/three-way splitters are legacy and must not be selected.

If your upstream returns 5xx, the bridge returns 502 to the agent and does not consume their payment — the order stays replayable, so the agent can retry for free with the same transaction. You never get paid for an upstream failure, and the agent never pays for one.

The services.json registry entry

new-provider.mjs prints the entry to paste into services.json → "services":

{
  "mybrand": {
    "name": "mybrand",
    "display_name": "MyBrand AI",
    "url": "https://mybrand.example",
    "logo": "mybrand",
    "service_type": "inference",
    "category": "inference",
    "tagline": "...",
    "modes": {
      "bridge": {
        "bridge_url": "https://bridge.aifinpay.io/mybrand",
        "chain": "polygon",
        "merchant_wallet": "0xYourWallet",
        "price_usd": 0.02
      }
    }
  }
}

Once merged and redeployed, agents discover you through:

The on-chain Payment events (the canonical source)
The aggregated /api/dashboard endpoint
The merchant lookup at /api/partner/:wallet
Automatic selection via /api/registry/best

What you get for the 1% fee

Pre-built SDKs

Agents pay you through the Python (aifinpay-agent), Node (@aifinpay/agent), and MCP (@aifinpay/mcp) surfaces — no work on your side.

Discovery

Appearance on the /api/dashboard and aifinpay.io marketplace pages.

Trusted identity

Agents carry on-chain AgentPassport identity you can trust without running your own KYC.

Multi-scheme facilitator

A canonical x402 facilitator translates between AiFinPay-native, Coinbase-x402, and (future) generic schemes — agents written for any of these can pay you.

You do not pay for agent onboarding (handled in the SDK) or network fees (paid by the agent submitting the transaction).

Production checklist

The scaffolded .env is for development. Before driving real volume:

Set REDIS_URL to share order/transaction state across instances (empty falls back to in-memory).
Use a hardware-secured wallet or a Safe for BRIDGE_MERCHANT_WALLET — don’t reuse a CI/CD-rotated EOA.
Move your upstream API key to a secret manager; the .env file is for development only.
Rate-limit by Polygon address at the application layer — the bundled express-rate-limit is per-IP, intended as anti-spam for the 402 challenge step.
Monitor your Payment events (or the dashboard). A merchant wallet missing receipts means an agent paid but the bridge didn’t deliver — that’s a refund case.

Questions or pilot scoping: open an issue at github.com/AiFinPay/sdk/issues.

Get started

Pay for services

Charge for your API

Reference

Become a provider

Start here instead

The partner-bridge route (requires us)

Config-only

Non-custodial & token-free

What you need

Fast path — config only, no code

The three knobs

Auth styles

Optional knobs

The on-chain split

The services.json registry entry

What you get for the 1% fee

Pre-built SDKs

Discovery

Trusted identity

Multi-scheme facilitator

Production checklist