AiFinPay Agent Transactions API
agent-transactions router — see backend/routes/agent-transactions.js
agent-transactions router — see backend/routes/agent-transactions.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-agent-transactions-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 Agent Transactions 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: agent_transactions
description: agent-transactions router — see backend/routes/agent-transactions.js
paths:
/v1/agents/{address}/transactions:
get:
tags:
- agent_transactions
summary: Read an agent's durable indexed settlements for one network
operationId: get_v1_agents_address_transactions
responses:
'200':
description: Durable chain-specific facts with stable pagination and explicit coverage.
content:
application/json:
schema:
type: object
required:
- address
- chain
- source
- coverage
- indexing
- transactions
- limit
- offset
- next_offset
properties:
address:
anyOf:
- type: string
pattern: ^0x[0-9a-fA-F]{40}$
- type: string
pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
description: Canonical case-preserving base58 public key; runtime decodes exactly32 bytes.
chain:
type: string
network:
type: string
enum:
- mainnet
- devnet
program:
type: string
pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
description: Canonical case-preserving base58 public key; runtime decodes exactly32 bytes.
source:
type: string
const: aifinpay_indexed_settlements
coverage:
type: string
indexing:
type:
- object
- 'null'
additionalProperties: true
properties:
coverage_kind:
type: string
const: retained_rpc_inventory
coverage_start:
type:
- integer
- 'null'
description: Earliest canonically proven retained inventory timestamp, Unix seconds; null for empty/unproved cold inventory. Does not attest archive completeness.
archive_complete:
type: boolean
const: false
complete:
type: boolean
description: 'For Solana only: retained RPC pagination was scanned, not full historical completeness.'
transactions:
type: array
items:
type: object
required:
- tx_hash
- log_index
- chain
- payment_id
- block_number
- block_ts
- agent_address
- merchant_address
- token_address
- total_amount
- merchant_amount
- treasury_fee
- ip_creator_fee
properties:
tx_hash:
anyOf:
- type: string
pattern: ^0x[0-9a-fA-F]{64}$
- type: string
pattern: ^[1-9A-HJ-NP-Za-km-z]+$
minLength: 64
maxLength: 88
description: Base58 Ed25519 transaction signature; runtime decodes exactly64 bytes.
log_index:
type: integer
minimum: 0
chain:
type: string
payment_id:
type:
- string
- 'null'
block_number:
type: string
pattern: ^[0-9]+$
block_ts:
type: string
format: date-time
agent_address:
anyOf:
- type: string
pattern: ^0x[0-9a-fA-F]{40}$
- type: string
pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
description: Canonical case-preserving base58 public key; runtime decodes exactly32 bytes.
merchant_address:
anyOf:
- type: string
pattern: ^0x[0-9a-fA-F]{40}$
- type: string
pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
description: Canonical case-preserving base58 public key; runtime decodes exactly32 bytes.
token_address:
anyOf:
- type: string
pattern: ^0x[0-9a-fA-F]{40}$
- type: string
pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
description: Canonical case-preserving base58 public key; runtime decodes exactly32 bytes.
network:
type: string
enum:
- mainnet
- devnet
program:
type: string
pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
description: Canonical case-preserving base58 public key; runtime decodes exactly32 bytes.
block_hash:
type: string
pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
description: Canonical case-preserving base58 public key; runtime decodes exactly32 bytes.
nonce:
type: string
pattern: ^(0|[1-9][0-9]{0,19})$
description: Exact unsigned64-bit lamports, validated at runtime.
order_id_hash:
type: string
pattern: ^0x[0-9a-fA-F]{64}$
route_id:
type: string
pattern: ^0x[0-9a-fA-F]{64}$
treasury_address:
type: string
pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
description: Canonical case-preserving base58 public key; runtime decodes exactly32 bytes.
cost_allocation:
type: string
enum:
- quote-exact
- unattributed
- shared-unavailable
description: Whole-transaction fee/preparation costs require the original one-settle quote proof; unknown/shared costs never discharge an issued budget.
fee_lamports:
anyOf:
- type: string
pattern: ^(0|[1-9][0-9]{0,19})$
description: Exact unsigned64-bit lamports, validated at runtime.
- type: 'null'
nonce_rent_lamports:
type: string
pattern: ^(0|[1-9][0-9]{0,19})$
description: Exact unsigned64-bit lamports, validated at runtime.
ata_rent_lamports:
anyOf:
- type: string
pattern: ^(0|[1-9][0-9]{0,19})$
description: Exact unsigned64-bit lamports, validated at runtime.
- type: 'null'
total_amount:
type: string
pattern: ^[0-9]+$
maxLength: 78
merchant_amount:
type: string
pattern: ^[0-9]+$
maxLength: 78
treasury_fee:
type: string
pattern: ^[0-9]+$
maxLength: 78
ip_creator_fee:
type: string
pattern: ^[0-9]+$
maxLength: 78
limit:
type: integer
offset:
type: integer
next_offset:
type:
- integer
- 'null'
'400':
description: Invalid wallet, missing Solana network selection or pagination.
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: string
chain:
type: string
detail:
type: string
supported_chains:
type: array
items:
type: string
'401':
$ref: '#/components/responses/AifpError'
'403':
$ref: '#/components/responses/AifpError'
'404':
$ref: '#/components/responses/AifpError'
'422':
description: Requested network has no configured history indexer.
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: string
chain:
type: string
detail:
type: string
supported_chains:
type: array
items:
type: string
'429':
$ref: '#/components/responses/AifpError'
'503':
description: Durable ledger or network indexer coverage is unavailable.
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: string
chain:
type: string
detail:
type: string
supported_chains:
type: array
items:
type: string
5XX:
$ref: '#/components/responses/AifpError'
security: []
parameters:
- name: address
in: path
required: true
schema:
anyOf:
- type: string
pattern: ^0x[0-9a-fA-F]{40}$
- type: string
pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
description: Canonical case-preserving base58 public key; runtime decodes exactly32 bytes.
- name: chain
in: query
schema:
type: string
default: polygon
- name: network
in: query
schema:
type: string
enum:
- mainnet
- devnet
description: Required for Solana wallets; never combines clusters.
- name: program
in: query
schema:
type: string
pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
description: Canonical case-preserving base58 public key; runtime decodes exactly32 bytes.
description: Optional exact program pin for selected Solana cluster; mismatch refuses.
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 25
- name: offset
in: query
schema:
type: integer
minimum: 0
maximum: 100000
default: 0
description: Public settlement facts only. A network must have a configured indexer; additional EVM networks return 503 while backfill is incomplete, failed or stale. This endpoint excludes arbitrary wallet transfers. Amounts are exact token base-unit decimal strings; use independently pinned chain/token decimals for display. It never substitutes another network's history.
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.