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:

Sign in with an email link and create a service.
Give it a payout address (a standard 0x… EVM address; settlement is on Polygon today).
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.
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.

That is the whole thing. Hosted Gateway walks through it with no code at all; SDK middleware 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

Every successful call generates exactly one Payment event on the verified B2BSplitter contract at 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":

{
  "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

​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

Start here instead

The partner-bridge route (requires us)

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

Production checklist