> ## Documentation Index > Fetch the complete documentation index at: https://docs.aifinpay.io/llms.txt > Use this file to discover all available pages before exploring further. # Become a provider > Charge AI agents per call by putting a config-only x402 bridge in front of your API — non-custodial, no contract to sign. **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](https://dash.aifinpay.io) — no repository, no approval, no contract: 1. Sign in with an email link and create a service. 2. Give it a payout address (a standard `0x…` EVM address; settlement is on Polygon today). 3. On the **Gateway** page, pick a slug and enter your upstream URL. Your paid endpoint is live immediately at `https://gateway.aifinpay.io/{your-slug}/…` — that is the URL you hand to agents. 4. Lock your origin so agents cannot bypass the paywall. **Read [Hosted Gateway](/charge/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.** That is the whole thing. [Hosted Gateway](/charge/gateway) walks through it with no code at all; [SDK middleware](/charge/dashboard) 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. Front any JSON HTTP API by editing a `.env` file. No bridge code to fork or maintain — the generic bridge is fully env-driven. 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. Run `scripts/new-provider.mjs` with your three knobs and identity flags: ```bash theme={null} 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`. Open the generated `.env` and fill in the one secret the scaffold leaves blank: ```bash theme={null} 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. The bridge code lives in `_generic-x402-bridge`; you point it at your scaffolded `.env`: ```bash theme={null} 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 ` | OpenAI, Venice, Tavily | | `x-api-key` | `x-api-key: ` | Exa | | `header` | `: ` | ElevenLabs (`UPSTREAM_AUTH_HEADER=xi-api-key`) | ### Optional knobs ```bash theme={null} 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 Every successful call generates exactly one `Payment` event on the verified `B2BSplitter` contract at [`0xE34Fc0E6694821c600Fa0955C0F74720ea6d8440`](https://polygonscan.com/address/0xE34Fc0E6694821c600Fa0955C0F74720ea6d8440). You keep **98.99%**; the protocol fee is **1.00%**. ``` agent ──payment──▶ B2BSplitter.payMatic │ ├──── 98.99% ────▶ YOUR merchant wallet ├──── 1.00% ────▶ AiFinPay treasury Safe └──── 0.01% ────▶ ipCreator (or treasury if unset) emit Payment(payer, merchant, address(0), totalAmount, merchantAmount, treasuryAmount, ipCreatorAmount, orderId) ``` You don't deploy or upgrade any contract, and you don't sign a partner agreement on-chain. The 1% protocol fee is structural — every `payMatic` call routes through the splitter, and the split is hard-coded by the Gnosis Safe owner. Agents can also pay in USDC/USDT via the standard x402 (ERC-3009) facilitator path; the same 98.99 / 1.00 / 0.01 split applies. 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"`: ```json theme={null} { "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 Agents pay you through the Python (`aifinpay-agent`), Node (`@aifinpay/agent`), and MCP (`@aifinpay/mcp`) surfaces — no work on your side. Appearance on the `/api/dashboard` and `aifinpay.io` marketplace pages. Agents carry on-chain `AgentPassport` identity you can trust without running your own KYC. 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`](https://github.com/AiFinPay/sdk/issues).