Skip to main content
This page covers the AIFP-1 merchant protocol — the one behind the hosted Gateway and the SDK middleware. If you are an agent paying for services, you want Pay for services instead; that is a different protocol with different headers.

​
Units

Everything is metered in billing units. One unit is **0.0001∗∗,so10,000unitsis0.0001**, so 10,000 units is 1. A call’s cost in units comes from its tier: An unrecognised tier prices as 1 unit. There are exactly three tiers — a quote requesting anything else is rejected with 400.

​
What you keep

Every settlement splits on-chain, atomically, in the same transaction that pays you. Nothing passes through an AiFinPay account first. The fee is charged on top of your price rather than deducted from it: you set what you want to earn per unit, and the agent pays that plus the fee. There is no minimum fee, no monthly cost and no withdrawal step — the funds arrive at your payout address in the settlement transaction itself.
Be realistic about scale before integrating. At the standard tier a call earns you about **0.0001∗∗—atenthofacent.Amillionpaidrequestsisroughly0.0001** — a tenth of a cent. A million paid requests is roughly 99. If your goal is revenue, this pays off at API-scale volume. If your goal is to stop AI crawlers taking your content for free, it works at any volume, because the point is the paywall rather than the amount.

​
Where the tier comes from

This surprises people, so it is worth stating plainly: the agent names the tier in its quote request. It is not read from the route you registered in the dashboard.
The tier stored on a resource in the dashboard is used for metering through the hosted Gateway and for labelling in analytics and receipts — not for pricing this quote. /v1/quote takes no API key. That is deliberate: the intended caller is the agent, which is untrusted by definition, and a quote commits you to nothing until it is settled on-chain. You can call it yourself to see exactly what your agents see.

​
Per-route weight

unit_weight on a registered resource overrides the tier for that one route — an integer from 1 to 100,000. Leave it empty and the tier’s weight applies. It takes effect when traffic runs through the hosted Gateway. If you verify receipts yourself in your own backend, the weight you pass to your own gate is what counts, and editing the field in the dashboard will not change your live billing.

​
Free allowance and daily caps

Two optional controls, both set per service on the dashboard’s Policies page:
  • Free units per agent — how much a new agent can spend with you before it has to pay. 0 disables the free tier.
  • Daily unit cap per agent — the most any single agent can spend with you in a day. Blank means no cap.
Two things about both that are easy to get wrong:
They count units, not requests. On a standard route one call spends one unit, but a premium route spends ten. A free allowance of 100 units is 100 standard calls — or 10 premium ones.They are one shared bucket per agent, across every route you have. Not per route. An agent that exhausts its free allowance on /search has exhausted it for /summarise too.
The daily cap limits a single agent, not your total traffic. Ten agents at a 1,000-unit daily cap can still spend 10,000 units between them.

​
Identifying agents

Agents may send a self-declared identifier:
It is what the free allowance, the daily cap and any per-agent allow/block rules are keyed on. Being self-declared, it is a convenience for policy, not an authentication mechanism — an agent that wants a fresh free allowance can simply send a different one. Treat the free tier as a marketing cost, not a security boundary.

​
What a receipt proves

A settled payment returns a signed receipt: an Ed25519 JWT you verify against https://api.aifinpay.io/.well-known/jwks.json. Verification is stateless — no shared secret, no call back to us. The receipt is pinned to:
  • aud — your merchant_id. A receipt bought for another service cannot unlock yours.
  • resource — the path it was bought for.
It is not pinned to an agent. The sub claim is self-declared by whoever called /v1/pay, and it is never compared against AIFP-Agent-Id. In practice the receipt is a bearer token: anyone holding it can spend down the same prepaid quota.Meter by receipt_id, and treat a leaked receipt the way you would treat a leaked API key — what it protects is the remaining batch, not an identity.

​
What URL to give agents

Depends on which integration you chose:
  • Hosted Gateway — give them your gateway base URL: https://gateway.aifinpay.io/{your-slug}/<path>. Every path under it is proxied to your upstream. Registering resources changes pricing and analytics, not routing.
  • SDK middleware / self-hosted — give them your own domain, exactly as you would without AiFinPay. There is no AiFinPay URL in the path; we only issue the quote and the receipt, and your server verifies it.

​
Networks

Settlement is verified on Polygon today: POL, USDC and USDT. A quote’s accepted_chains tells an agent what it may pay on, and a settlement on a chain we cannot verify is refused rather than accepted on trust. More networks appear here as their verification lands.