AiFinPay Settlement API
settlement router — see backend/routes/settlement.js
settlement router — see backend/routes/settlement.js
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/aifinpay-io:aifinpay-io-settlement-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: AiFinPay Settlement API
version: 5.3.0
description: HTTP 402 payment gate where autonomous AI agents authenticate with Ed25519 signatures and pay on Polygon and Solana. This document is generated from backend/routes/*.js — do not hand-edit. Regenerate with `node backend/scripts/build-openapi.mjs`.
servers:
- url: https://api.aifinpay.io
description: Production (api)
- url: https://bridge.aifinpay.io
description: Production (bridge)
tags:
- name: Settlement
description: settlement router — see backend/routes/settlement.js
paths:
/v1/settlement/routes:
get:
tags:
- Settlement
summary: List configured v1.3 settlement routes
operationId: get_v1_settlement_routes
responses:
'200':
description: Configured routes; no settlement is enabled by this request.
content:
application/json:
schema:
type: object
required:
- routes
properties:
routes:
type: array
items:
type: object
required:
- route_class
- profile
- network
- chain_id
- testnet
- name
- native_asset
- stable_assets
- explorer
- live
- splitter
- splitter_version
- runtime_code_hash
properties:
route_class:
type: string
enum:
- AIFP-1
- AIFP-2
profile:
type: object
required:
- route_class
- settlement_semantics
- treasury_bps
- creator_bps
- fee_on_top
- required_splitter_version
properties:
route_class:
type: string
enum:
- AIFP-1
- AIFP-2
settlement_semantics:
type: string
const: gross-inclusive
treasury_bps:
type: integer
minimum: 0
maximum: 10000
creator_bps:
type: integer
minimum: 0
maximum: 10000
fee_on_top:
type: boolean
const: false
required_splitter_version:
type: string
const: '1.3'
network:
type: string
chain_id:
type: integer
testnet:
type: boolean
description: True only for a canonical test network. Testnet settlement additionally requires explicit server dev mode.
name:
type: string
native_asset:
type: string
stable_assets:
type: object
additionalProperties:
type: object
required:
- address
- decimals
- issuer
properties:
address:
type: string
pattern: ^0x[0-9a-fA-F]{40}$
decimals:
type: integer
const: 6
issuer:
type: string
explorer:
type: string
format: uri
live:
type: boolean
description: Configured availability, including the registry flag, supersession and validity window. Not an RPC health or deployment attestation.
splitter:
type: string
pattern: ^0x[0-9a-fA-F]{40}$
splitter_version:
type: string
const: '1.3'
runtime_code_hash:
type: string
pattern: ^0x[0-9a-fA-F]{64}$
disabled_reason:
type: string
description: Present when live is false.
'400':
$ref: '#/components/responses/AifpError'
'401':
$ref: '#/components/responses/AifpError'
'403':
$ref: '#/components/responses/AifpError'
'404':
$ref: '#/components/responses/AifpError'
'429':
$ref: '#/components/responses/AifpError'
5XX:
$ref: '#/components/responses/AifpError'
security: []
description: Read-only registry discovery. Disabled routes remain visible with live=false and disabled_reason. Callers must independently verify the route before signing.
parameters:
- name: route_class
in: query
required: false
schema:
type: string
enum:
- AIFP-1
- AIFP-2
/v1/settlement/invoice:
post:
tags:
- Settlement
summary: Build a gross-inclusive v1.3 settlement instruction
operationId: post_v1_settlement_invoice
responses:
'200':
description: Successful response
content:
application/json:
schema:
additionalProperties: true
'400':
$ref: '#/components/responses/AifpError'
'401':
$ref: '#/components/responses/AifpError'
'403':
$ref: '#/components/responses/AifpError'
'404':
$ref: '#/components/responses/AifpError'
'409':
description: Route is disabled, superseded, outside its validity window, unknown or not v1.3.
content:
application/json:
schema:
$ref: '#/components/schemas/AifpError'
'429':
$ref: '#/components/responses/AifpError'
5XX:
$ref: '#/components/responses/AifpError'
security: []
description: Requires a currently enabled canonical route. Rejects unknown assets, zero payout addresses, oversized orders and invalid expiry before returning calldata. The caller signs and submits from its own wallet.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- route_class
- chain
- asset
- gross_amount
- order_id
anyOf:
- required:
- merchant_wallet
- required:
- provider_wallet
properties:
route_class:
type: string
enum:
- AIFP-1
- AIFP-2
chain:
type: string
description: network returned by GET /v1/settlement/routes
asset:
type: string
description: The route's native_asset or one of its stable_assets keys; case insensitive.
gross_amount:
type: string
pattern: ^[1-9][0-9]{0,77}$
description: Positive decimal uint256 in atomic units, at most 2^256-1. Includes the protocol fee.
merchant_wallet:
type: string
pattern: ^0x(?!0{40}$)[0-9a-fA-F]{40}$
provider_wallet:
type: string
pattern: ^0x(?!0{40}$)[0-9a-fA-F]{40}$
order_id:
type: string
minLength: 1
maxLength: 256
description: Nonblank, at most 256 UTF-8 bytes. Bytes are validated separately from character length.
valid_until:
type: integer
description: Unix seconds, greater than the server's current time and no more than 1200 seconds ahead. Omit for 900 seconds; null is invalid.
components:
responses:
AifpError:
description: AIFP-* error envelope. See backend/server.js safe error handler.
content:
application/json:
schema:
$ref: '#/components/schemas/AifpError'
schemas:
AifpError:
type: object
required:
- error
properties:
error:
type: string
description: AIFP-{status} code, or domain-specific string (e.g. csrf_origin_denied)
detail:
type: string
request_id:
type: string
description: AIFP-Request-Id for log correlation
securitySchemes:
reportingCapability:
type: apiKey
in: header
name: AIFP-Reporting-Token
description: Observation/identity-removal capability only; no spending, access or ownership authority.
reportingOwnerSession:
type: apiKey
in: cookie
name: __aifinpay_user_session
description: Existing owner session, current tenant/site and session-epoch validation. Browser writes also require CSRF Origin checks.
agentEd25519:
type: apiKey
in: header
name: x-agent-pubkey
description: 'Ed25519-signed native-auth v2 request. Companion headers: x-nonce, x-signature, x-aifinpay-auth-version. The proof binds canonical origin, method, resource, body hash, and expiry. GET /nonce provides migration diagnostics only; start with an unauthenticated request to receive a v2 challenge.'
x402Payment:
type: apiKey
in: header
name: X-PAYMENT-RESPONSE
description: x402 payment proof, base64 JSON envelope. Issued by the paying agent's wallet after broadcasting the on-chain tx. See /.well-known/x402.json.
userSession:
type: apiKey
in: cookie
name: aifinpay_session
description: Browser session cookie for /api/me/* — sameSite=Lax, CSRF-guarded.
agentClaim:
type: apiKey
in: cookie
name: __aifinpay_agent_claim
description: Set by redeeming a one-time claim link (POST /api/me/claim-url). Valid 10 minutes, accepted only by /api/me/agents/challenge and /api/me/agents/claim.
adminSession:
type: apiKey
in: cookie
name: aifinpay_admin_session
description: Admin session cookie. ADMIN_ALLOWED_IPS allowlist in effect.
partnerSession:
type: apiKey
in: cookie
name: aifinpay_partner_session
description: Partner session cookie for /api/partners/me/*.
merchantSecret:
type: apiKey
in: header
name: AIFP-Merchant-Secret
description: Per-merchant API key for /v1/merchants/* writes.
ingestHmac:
type: apiKey
in: header
name: x-ingest-signature
description: HMAC signature for /api/internal/* and /api/telemetry.