AiFinPay Me Agents API
me-agents router — see backend/routes/me-agents.js
me-agents router — see backend/routes/me-agents.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-me-agents-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 Me Agents 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: me_agents
description: me-agents router — see backend/routes/me-agents.js
paths:
/api/me/agents:
get:
tags:
- me_agents
summary: GET /api/me/agents
operationId: get_api_me_agents
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'
'429':
$ref: '#/components/responses/AifpError'
5XX:
$ref: '#/components/responses/AifpError'
security:
- userSession: []
/api/me/agents/{address}/statement:
get:
tags:
- me_agents
summary: GET /api/me/agents/:address/statement
operationId: get_api_me_agents_address_statement
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'
'429':
$ref: '#/components/responses/AifpError'
'503':
description: Durable usage or independently verified requested-window coverage unavailable; no zero-valued fallback totals.
5XX:
$ref: '#/components/responses/AifpError'
security:
- userSession: []
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
const: solana
- name: network
in: query
schema:
type: string
enum:
- mainnet
- devnet
description: Required for public Solana calls; owner dashboard must select its bound cluster.
- 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: Solana identities preserve base58 case and select network=mainnet|devnet with optional exact pinned program. Retained original receipts and used billing units are PostgreSQL-authoritative, survive cache loss/recovery and exclude closed legacy program records. No bearer JWT is returned. Solana aggregates return503 until retained RPC coverage independently covers the requested window; empty/pruned inventory does not imply zero totals.
/api/me/agents/overview:
get:
tags:
- me_agents
summary: GET /api/me/agents/overview
operationId: get_api_me_agents_overview
responses:
'200':
description: Legacy address list by default; grouped logical-agent view when view=grouped
content:
application/json:
schema:
oneOf:
- type: object
properties:
window:
type: integer
agents:
type: array
items:
$ref: '#/components/schemas/AgentWalletView'
required:
- window
- agents
- $ref: '#/components/schemas/GroupedAgentOverview'
'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:
- userSession: []
x-aifinpay-grouped-overview: 1
parameters:
- name: view
in: query
required: false
schema:
type: string
enum:
- grouped
description: Omit for the backward-compatible address list; grouped returns logical agents with verified child wallets.
/api/me/summary:
get:
tags:
- me_agents
summary: GET /api/me/summary
operationId: get_api_me_summary
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'
'429':
$ref: '#/components/responses/AifpError'
5XX:
$ref: '#/components/responses/AifpError'
security:
- userSession: []
/api/me/wallet:
get:
tags:
- me_agents
summary: GET /api/me/wallet
operationId: get_api_me_wallet
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'
'429':
$ref: '#/components/responses/AifpError'
5XX:
$ref: '#/components/responses/AifpError'
security:
- userSession: []
/api/me/agents/{address}/receipts:
get:
tags:
- me_agents
summary: GET /api/me/agents/:address/receipts
operationId: get_api_me_agents_address_receipts
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'
'429':
$ref: '#/components/responses/AifpError'
5XX:
$ref: '#/components/responses/AifpError'
security:
- userSession: []
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
const: solana
- name: network
in: query
schema:
type: string
enum:
- mainnet
- devnet
description: Required for public Solana calls; owner dashboard must select its bound cluster.
- 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: Solana identities preserve base58 case and select network=mainnet|devnet with optional exact pinned program. Retained original receipts and used billing units are PostgreSQL-authoritative, survive cache loss/recovery and exclude closed legacy program records. No bearer JWT is returned.
/api/me/agents/{address}/telemetry:
get:
tags:
- me_agents
summary: GET /api/me/agents/:address/telemetry
operationId: get_api_me_agents_address_telemetry
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'
'429':
$ref: '#/components/responses/AifpError'
5XX:
$ref: '#/components/responses/AifpError'
security:
- userSession: []
parameters:
- name: address
in: path
required: true
schema:
type: string
description: Agent's on-chain address (EVM or Solana)
/api/me/agents/{address}/policy:
get:
tags:
- me_agents
summary: GET /api/me/agents/:address/policy
operationId: get_api_me_agents_address_policy
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'
'429':
$ref: '#/components/responses/AifpError'
5XX:
$ref: '#/components/responses/AifpError'
security:
- userSession: []
parameters:
- name: address
in: path
required: true
schema:
type: string
description: Agent's on-chain address (EVM or Solana)
put:
tags:
- me_agents
summary: PUT /api/me/agents/:address/policy
operationId: put_api_me_agents_address_policy
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'
'429':
$ref: '#/components/responses/AifpError'
5XX:
$ref: '#/components/responses/AifpError'
security:
- userSession: []
parameters:
- name: address
in: path
required: true
schema:
type: string
description: Agent's on-chain address (EVM or Solana)
/api/me/agent-groups/{agentId}:
patch:
tags:
- me_agents
summary: PATCH /api/me/agent-groups/:agentId
operationId: patch_api_me_agent-groups_agentId
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'
'429':
$ref: '#/components/responses/AifpError'
5XX:
$ref: '#/components/responses/AifpError'
security:
- userSession: []
parameters:
- name: agentId
in: path
required: true
schema:
type: string
delete:
tags:
- me_agents
summary: DELETE /api/me/agent-groups/:agentId
operationId: delete_api_me_agent-groups_agentId
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'
'429':
$ref: '#/components/responses/AifpError'
5XX:
$ref: '#/components/responses/AifpError'
security:
- userSession: []
parameters:
- name: agentId
in: path
required: true
schema:
type: string
/api/me/agent-groups/{agentId}/policy:
get:
tags:
- me_agents
summary: GET /api/me/agent-groups/:agentId/policy
operationId: get_api_me_agent-groups_agentId_policy
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'
'429':
$ref: '#/components/responses/AifpError'
5XX:
$ref: '#/components/responses/AifpError'
security:
- userSession: []
parameters:
- name: agentId
in: path
required: true
schema:
type: string
description: Owner-only policy controls. Values apply separately to each verified child wallet; this is NOT a shared agent cap. Writes update all child policies atomically.
put:
tags:
- me_agents
summary: PUT /api/me/agent-groups/:agentId/policy
operationId: put_api_me_agent-groups_agentId_policy
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'
'429':
$ref: '#/components/responses/AifpError'
5XX:
$ref: '#/components/responses/AifpError'
security:
- userSession: []
parameters:
- name: agentId
in: path
required: true
schema:
type: string
description: Owner-only policy controls. Values apply separately to each verified child wallet; this is NOT a shared agent cap. Writes update all child policies atomically.
/api/me/agents/challenge:
post:
tags:
- me_agents
summary: POST /api/me/agents/challenge
operationId: post_api_me_agents_challenge
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'
'429':
$ref: '#/components/responses/AifpError'
5XX:
$ref: '#/components/responses/AifpError'
security:
- userSession: []
- agentClaim: []
description: Start a signed wallet challenge. Optional agent_id selects an existing OWNED logical agent for a full owner session only. The target and verified claim-session identity are stored with the challenge and cannot be changed at signature submission.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
address:
type: string
chain:
type: string
agent_id:
type:
- string
- 'null'
required:
- address
/api/me/agents/claim:
post:
tags:
- me_agents
summary: POST /api/me/agents/claim
operationId: post_api_me_agents_claim
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'
'429':
$ref: '#/components/responses/AifpError'
5XX:
$ref: '#/components/responses/AifpError'
security:
- userSession: []
- agentClaim: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- label
properties:
label:
type: string
additionalProperties: true
/api/me/agents/{address}:
patch:
tags:
- me_agents
summary: PATCH /api/me/agents/:address
operationId: patch_api_me_agents_address
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'
'429':
$ref: '#/components/responses/AifpError'
5XX:
$ref: '#/components/responses/AifpError'
security:
- userSession: []
parameters:
- name: address
in: path
required: true
schema:
type: string
description: Agent's on-chain address (EVM or Solana)
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- label
- alert_email_on_daily_spend_usd
- preferred_chain
properties:
label:
type: string
alert_email_on_daily_spend_usd:
type: string
preferred_chain:
type: string
additionalProperties: true
delete:
tags:
- me_agents
summary: DELETE /api/me/agents/:address
operationId: delete_api_me_agents_address
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'
'429':
$ref: '#/components/responses/AifpError'
5XX:
$ref: '#/components/responses/AifpError'
security:
- userSession: []
parameters:
- name: address
in: path
required: true
schema:
type: string
description: Agent's on-chain address (EVM or Solana)
/v1/agents/{address}/policy:
get:
tags:
- me_agents
summary: GET /v1/agents/:address/policy
operationId: get_v1_agents_address_policy
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'
'429':
$ref: '#/components/responses/AifpError'
5XX:
$ref: '#/components/responses/AifpError'
security: []
parameters:
- name: address
in: path
required: true
schema:
type: string
description: Agent's on-chain address (EVM or Solana)
components:
responses:
AifpError:
description: AIFP-* error envelope. See backend/server.js safe error handler.
content:
application/json:
schema:
$ref: '#/components/schemas/AifpError'
schemas:
GroupedAgentOverview:
type: object
properties:
window:
type: integer
minimum: 1
maximum: 90
agents:
type: array
items:
$ref: '#/components/schemas/LogicalAgentView'
required:
- window
- agents
LogicalAgentView:
type: object
properties:
agent_id:
type:
- string
- 'null'
label:
type:
- string
- 'null'
wallet_id:
type:
- string
- 'null'
source:
type: string
enum:
- claimed
- partner
wallets:
type: array
minItems: 1
items:
$ref: '#/components/schemas/AgentWalletView'
balance_usd_total:
type:
- number
- 'null'
balance_coverage:
type: object
properties:
priced_wallets:
type: integer
minimum: 0
total_wallets:
type: integer
minimum: 0
required:
- priced_wallets
- total_wallets
calls_window:
type:
- integer
- 'null'
minimum: 0
spent_usd_window:
type:
- number
- 'null'
history_coverage:
type: object
properties:
supported_wallets:
type: integer
minimum: 0
total_wallets:
type: integer
minimum: 0
required:
- supported_wallets
- total_wallets
last_activity_ts:
type:
- integer
- 'null'
top_merchant:
type:
- string
- 'null'
health:
type: string
enum:
- ok
- attention
- alert
required:
- agent_id
- label
- wallet_id
- source
- wallets
- balance_usd_total
- balance_coverage
- calls_window
- spent_usd_window
- history_coverage
- last_activity_ts
- top_merchant
- health
AgentWalletView:
type: object
properties:
address:
type: string
chain:
type: string
label:
type:
- string
- 'null'
wallet_id:
type:
- string
- 'null'
balance_usd:
type:
- number
- 'null'
balance_native:
type:
- number
- 'null'
balance_usd_total:
type:
- number
- 'null'
calls_window:
type:
- integer
- 'null'
minimum: 0
spent_usd_window:
type:
- number
- 'null'
last_activity_ts:
type:
- integer
- 'null'
health:
type: string
enum:
- ok
- attention
- alert
required:
- address
- chain
- balance_usd
- balance_native
- calls_window
- spent_usd_window
- health
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.