Call Paid APIs

Technical reference for AI agents that discover and call paid APIs on FluxA AgentMarket. For the website walkthrough, see Browse the Marketplace. For LLM models, see Models & Units.

The flow is:

1. Find an API with the discovery endpoint.
2. Read its endpoints and prices at https://router.fluxapay.xyz/api/{slug}.
3. Call an endpoint. Paid endpoints answer 402 Payment Required with an x402 challenge.
4. Pay the challenge with FluxA Agent Wallet and resend the request with X-Payment.

Discovery

GET https://agentmarket.fluxapay.xyz/api/discover

Lists published APIs, skills and models. No authentication. Returns JSON by default. Send Accept: text/markdown or add ?format=md for a Markdown catalog.

curl "https://agentmarket.fluxapay.xyz/api/discover?search=company+data"

Query parameters:

Param	Default	Description
type	api	api, skill, model, or a comma-separated mix such as api,skill,model
search	—	Fuzzy match. Every word must appear in the name, description, tags or slug. Scans the whole catalog and ignores limit/offset
query	—	Exact, case-insensitive match on a slug, tag, or (for models) provider or provider/id. Scans the whole catalog and ignores limit/offset
tags	—	Comma-separated tag filter
limit	50	Page size when browsing. Max 1000
offset	0	Page offset when browsing
format	—	md returns Markdown

Response (200):

{
  "name": "FluxA Discovery",
  "platformBase": "https://agentmarket.fluxapay.xyz",
  "proxyBase": "https://router.fluxapay.xyz",
  "payment": "Use fluxa-wallet (npx @fluxa-pay/fluxa-wallet) to handle x402 payments",
  "tip": "Find tools two ways: ...",
  "apiServers": [
    {
      "slug": "agent-data-tools",
      "name": "Agent Data Tools",
      "description": "180 pay-per-call data tools for agents behind one URL ...",
      "tags": ["crypto", "data", "utilities"],
      "priceUsd": { "min": 0.01, "max": 0.01 },
      "source": "fluxa",
      "urls": {
        "access": "https://router.fluxapay.xyz/api/agent-data-tools",
        "integrationGuide": "https://agentmarket.fluxapay.xyz/marketplace/apis/agent-data-tools/skills.md"
      }
    }
  ],
  "pagination": { "offset": 0, "limit": 50, "returned": 50, "total": 241, "nextOffset": 50 },
  "more": {
    "note": "Only if nothing in the FluxA catalog above fits your task, ...",
    "sources": [ { "name": "x402 Bazaar (Coinbase)", "discover": "GET https://api.cdp.coinbase.com/...", "...": "..." } ]
  }
}

Field	Description
apiServers[]	APIs. priceUsd is the min/max per-call price across endpoints (null if none). urls.access is the base URL to call; urls.integrationGuide is an agent-readable Markdown guide
apiServers[].source	fluxa: published on AgentMarket and called through the router. bazaar: a curated external x402 endpoint; its urls.access points at that service directly. Prefer fluxa items
skills[]	Present when type includes skill. Each has install (an npx -y skills add … command) and urls.details
models[]	Present when type includes model. See Discover models
pagination	nextOffset is the offset for the next page, or null when there are no more
more	Other x402 catalogs to try only when nothing in AgentMarket fits
search, query	Echoed back when you used them

Errors:

Status	Meaning
400	Invalid type. Valid types: api, skill, model
500	Internal error. Retry later

CLI: fluxa-wallet market search "<keywords>" searches APIs, skills and models at once.

Integration guide for one API

curl https://agentmarket.fluxapay.xyz/marketplace/apis/{slug}/skills.md

Returns Markdown that tells an agent how to call that API, including endpoints, prices and the payment steps. A guide for the whole API catalog is at https://agentmarket.fluxapay.xyz/marketplace/apis/skills.md.

Endpoints and prices of one API

GET https://router.fluxapay.xyz/api/{slug}

No authentication. Returns the API's enabled endpoints.

{
  "name": "Agent Data Tools",
  "description": "180 pay-per-call data tools for agents behind one URL ...",
  "endpoints": [
    {
      "path": "/",
      "method": "GET",
      "description": "Any tool by its path, GET with query parameters, $0.01 a call ...",
      "price": 0.01,
      "currency": "USDC",
      "enabled": true,
      "inputSchema": null
    }
  ],
  "paymentRequired": true,
  "networks": ["base", "fluxa-monetize-credits"],
  "payTo": "0x..."
}

price is in USD per call. 0 means the endpoint is free. method: "ALL" means any HTTP method is accepted. networks lists the payment networks you can pay on (see Payment).

Making calls

Call https://router.fluxapay.xyz/api/{slug}{endpoint-path} with the method, query and body the endpoint expects. Paths are prefix-matched, so /users also serves /users/123.

Step 1: call without payment

curl -i "https://router.fluxapay.xyz/api/agent-data-tools/weather?city=London"

A paid endpoint returns 402 with the x402 challenge:

{
  "x402Version": 1,
  "error": "X-PAYMENT header is required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "10000",
      "payTo": "0x...",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "resource": "https://router.fluxapay.xyz/api/agent-data-tools/weather?city=London",
      "description": "API access: /weather"
    },
    {
      "scheme": "exact",
      "network": "fluxa-monetize-credits",
      "maxAmountRequired": "1",
      "payTo": "monetize.fluxapay.xyz",
      "asset": "fluxa-monetize-credit",
      "...": "..."
    }
  ]
}

Step 2: pay the challenge

Pass the whole 402 body to FluxA Agent Wallet. It picks the accepts entry that matches your mandate's currency and returns a payment token.

fluxa-wallet x402-v3 --mandate <mandateId> --payload "$PAYLOAD_402_BODY"
# -> data.xPaymentB64

You need a signed spending mandate first (fluxa-wallet mandate-create …, approved once by the human). See x402 Payment and Mandates.

Step 3: resend with X-Payment

curl "https://router.fluxapay.xyz/api/agent-data-tools/weather?city=London" \
  -H "X-Payment: <xPaymentB64>" \
  -H "X-Agent-ID: <your-agent-id>"

The router checks the payment, calls the API, and charges only after the API answers successfully. If the API fails, you are not charged.

On success, the API's own response is returned unchanged, plus a settlement header:

X-Payment-Settlement: {"success":true,"transaction":"0xabc...","network":"base","payer":"0x..."}

Every response also carries X-FluxA-Request-Id. Quote it when you contact support.

Headers

Header	Required	Description
X-Payment	On paid endpoints	The x402 payment token from FluxA Agent Wallet
X-Agent-ID	Only for APIs with agent authentication	Your agent ID, used for usage attribution. APIs that require agent authentication need your agent JWT here instead (see below)
X-Creator-Uid	No	8-character hex creator ID for referral attribution. Can also go in the path: /api/{slug}/{creatorUid}/{path}
X-Skill-Name	No	Skill name, for analytics
X-Task-Id	No	Task ID, for tracing

Agent authentication

Some APIs require a verified agent identity. For those, put your agent JWT (not the plain agent ID) in X-Agent-ID:

# Print a fresh JWT
fluxa-wallet refreshJWT

curl "https://router.fluxapay.xyz/api/{slug}/path" \
  -H "X-Agent-ID: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "X-Payment: <xPaymentB64>"

fluxa-wallet status shows your agent ID and whether the agent is configured. It does not print the JWT; use fluxa-wallet refreshJWT for that, or the AGENT_JWT environment variable if you set one. If you are unsure whether an API needs a JWT, call it with the plain agent ID. You get a 401 with a clear message if a JWT is required.

Payment

Network	Asset	Amount units
base	USDC on Base	6 decimals: 10000 = $0.01
fluxa-monetize-credits	Monetize Credits (asset fluxa-monetize-credit)	2 decimals: 1 = 0.01 MC = $0.01

fluxa-monetize-credits is a network identifier, and the payTo value monetize.fluxapay.xyz on that network is an identifier for the AgentMarket credits recipient. Both are written exactly as they appear on the wire; neither is a website you need to visit.

The owner of an API cannot pay for their own API.

Errors

Errors produced by the router use one shape, so you can always tell whether you were charged:

{
  "error": "Upstream provider returned 500. No funds were deducted.",
  "code": "UPSTREAM_ERROR",
  "settled": false
}

Field	Description
error	Human-readable reason. Ends with a statement about whether funds were deducted
code	Machine-readable reason (table below)
settled	false: nothing was charged. "unknown": the charge could not be confirmed either way; you can safely retry the same request
retryable	Present on some errors. true means retrying may succeed
upstream_status, upstream_body	Present when the API itself returned an error

Status	code	Meaning
400	DECODE_FAILED	The X-Payment token could not be read
401	—	The API requires an agent JWT in X-Agent-ID, or the JWT is invalid or expired. Get a fresh one with fluxa-wallet refreshJWT
402	—	Payment required. Pay the challenge in the body and retry
402	(varies)	The payment was rejected, or charging it failed. Not charged
403	SELF_PURCHASE	You cannot buy your own API
404	—	Unknown API slug, or the path matches no published endpoint
502	UPSTREAM_ERROR / UPSTREAM_UNREACHABLE	The API failed or could not be reached. Not charged
503	(varies)	Payments or the API are temporarily unavailable. Retry later; honor Retry-After if present