FlareHQ REST API Reference — Full Developer Overview

The FlareHQ REST API gives you programmatic access to USDC payment sessions, on-chain escrow, per-second token streams, micro-payment proxies, autonomous agent identity, agentic commerce jobs, and merchant account management — all settled on Arc Mainnet (chain ID 5042). Every request goes to a single base URL and authenticates with a single API key, making integration straightforward whether you’re building a storefront, a server-side backend, or an autonomous agent.

Production network: Arc Mainnet (chain ID 5042, RPC https://rpc.mainnet.arc.io, explorer https://explorer.arc.io, USDC 0x3600000000000000000000000000000000000000, 6 decimals, CCTP domain 26). Arc Testnet (chain ID 5042002, RPC https://rpc.testnet.arc.network, explorer https://testnet.arcscan.app) is the development/test environment only.

Base URL

All API requests target the following base URL. There are no version prefixes — endpoint paths begin at /api/.

https://flarehq.xyz

Authentication

Every request must carry a x-api-key header containing your FlareHQ API key (arc_live_..., issued by POST /api/merchant/verify or POST /api/keys), or — on routes that support it — a merchant_token/consumer_token session cookie. Unauthenticated requests are rejected with HTTP 401.

curl https://flarehq.xyz/api/payments/initialize \
  -H "x-api-key: arc_live_your_key_here" \
  -H "Content-Type: application/json"

API keys are issued in the arc_live_... format. Never commit any key to source control.

Key types

Key	Format	Behaviour
Merchant API key	`arc_live_...`	Issued once by `POST /api/merchant/verify`; per-merchant, active + verified required
Service API key	`arc_live_...`	Provisioned via `POST /api/keys`; used for internal/server-to-server calls

Request Format

Send all request bodies as JSON and include the Content-Type: application/json header. Query-string parameters are supported where documented (e.g. filtering and pagination on list endpoints).

curl -X POST https://flarehq.xyz/api/payments/initialize \
  -H "x-api-key: arc_live_..." \
  -H "Content-Type: application/json" \
  -d '{"amount": "10.00", "currency": "USDC"}'

Response Envelope

All responses return a JSON object. Successful responses include "success": true alongside endpoint-specific fields. Failed responses include "success": false and a human-readable error string.

{
  "success": true,
  "reference": "arc_ref_k7x2m9...",
  "checkoutUrl": "https://flarehq.xyz/checkout/arc_ref_k7x2m9...",
  "data": {
    "amount": "10.00",
    "currency": "USDC",
    "status": "ready"
  }
}

{
  "success": false,
  "error": "Authentication required. Provide a valid x-api-key, or sign in to create a payment."
}

HTTP status codes

Code	Meaning
`200`	Request succeeded
`400`	Invalid or missing request parameters
`401`	Missing or invalid API key
`404`	Resource not found
`429`	Rate limit exceeded
`500`	Internal server error

Rate Limits

FlareHQ enforces per-API-key rate limits to ensure fair use. When a limit is exceeded the API returns HTTP 429. Back off and retry after the Retry-After interval indicated in the response headers.

Endpoint group	Limit
Default (all endpoints)	50 requests / minute
Payment endpoints (`/api/payments/*`)	30 requests / minute
Streaming (`/api/payments/stream/*`)	20 requests / minute
Escrow (`/api/escrow/*`)	20 requests / minute
Agents (`/api/agent/*`)	10 requests / minute
Nano payments (`/api/payments/nano/*`)	100 requests / minute
Withdrawals & key management	5 requests / minute

Payment initialization and verification share the same payments rate-limit bucket. If you are building a high-throughput integration, cache payment status locally and avoid polling /verify more often than necessary.

Environments

Environment	Purpose	API key format	Funds
Production (Arc Mainnet, `5042`)	Live payments at flarehq.xyz	`arc_live_...`	Real USDC on Arc Mainnet
Testnet (Arc Testnet, `5042002`)	Development and QA only	`arc_live_...`	Free test USDC from faucet.circle.com

Production transactions settle in real USDC on Arc Mainnet (chain ID 5042). Testnet transactions use Circle’s test USDC token and settle on Arc Testnet (chain ID 5042002). No real funds ever move during testnet development. Get test USDC at faucet.circle.com.

Endpoint Groups

The FlareHQ API is organised into functional groups. Each group maps to a distinct /api/ path prefix.

Payments — `/api/payments/*`

Create and verify USDC payment sessions with a hosted checkout page. Supports merchant-initiated payment links, consumer send/request flows, scheduled and nano payments, and autonomous agent payments. → Initialize · → Verify · → History · → Payment Links · → Scheduled · → Nano

Escrow — `/api/escrow/*`

Lock USDC on-chain into a smart contract escrow and release it programmatically once conditions are met. Useful for milestone-based payments, conditional delivery, and dispute-safe commerce. → Create · → Release · → Dispute · → Status

Streaming — `/api/payments/stream/*`

Open, manage, and close per-second USDC payment streams. Built for real-time service billing, agentic compute pricing, and any use case where continuous micro-settlement replaces lump-sum invoices. → Create · → Stop · → Withdraw · → List

CCTP Bridge — `/api/cctp/*`

Bridge native USDC across chains via Circle CCTP. The documented CCTP flow targets Arc Mainnet for development — see the CCTP guide for current production bridging status. → Transfer · → Status

Checkout — `/api/checkout/*`

Public helpers for the hosted checkout experience — render a payment QR code and trigger settlement for a checkout reference. → QR · → Pay

x402 — `/api/x402/*`

Micro-payment proxy and marketplace layer using the x402 HTTP payment protocol. Enables any HTTP resource or API to gate access behind a USDC micro-payment, fulfilled automatically by compliant agents or wallets. → Pay · → Verify & Withdraw · → Marketplace · → EOA Wallet · → Gateway

Agents — `/api/agent/*`

Register and manage ERC-8004 agent identities with on-chain SCA wallets. Agents created through this group can be referenced by their scaAddress in payment and job requests, enabling fully autonomous on-chain spending. → Deploy · → Status · → Reputation · → Brain · → Validation

Jobs — `/api/jobs/*`

Create and fulfil ERC-8183 agentic commerce job listings. Agents bid on, accept, and settle jobs with automatic USDC compensation, forming the backbone of FlareHQ’s autonomous agent marketplace. → Create · → Fund · → Submit · → Complete · → List · → Detail

Merchant — `/api/merchant/*`

Manage your merchant account: sign up, verify, configure payout wallet addresses, view aggregate revenue metrics, withdraw funds, and create payment links. → Signup · → Login · → Verify · → Me · → Dashboard · → Wallet · → Wallet Connect · → Withdraw

Consumer — `/api/consumer/*`

Consumer-facing session, balance, and activity endpoints that power FlareHQ Flow’s send/request wallet experience. → Session · → Balance · → Activity

Payroll — `/api/payroll/*`

Run batch USDC payroll to many recipients in a single call, with per-recipient results and signature-gated payouts to external wallets. → Run

If you are building an integration for the first time, start with Initialize Payment to create a production payment session on Arc Mainnet in under five minutes using only curl.

​Base URL

​Authentication

​Key types

​Request Format

​Response Envelope

​HTTP status codes

​Rate Limits

​Environments

​Endpoint Groups

​Payments — /api/payments/*

​Escrow — /api/escrow/*

​Streaming — /api/payments/stream/*

​CCTP Bridge — /api/cctp/*

​Checkout — /api/checkout/*

​x402 — /api/x402/*

​Agents — /api/agent/*

​Jobs — /api/jobs/*

​Merchant — /api/merchant/*

​Consumer — /api/consumer/*

​Payroll — /api/payroll/*

Base URL

Authentication

Key types

Request Format

Response Envelope

HTTP status codes

Rate Limits

Environments

Endpoint Groups

Payments — `/api/payments/*`

Escrow — `/api/escrow/*`

Streaming — `/api/payments/stream/*`

CCTP Bridge — `/api/cctp/*`

Checkout — `/api/checkout/*`

x402 — `/api/x402/*`

Agents — `/api/agent/*`

Jobs — `/api/jobs/*`

Merchant — `/api/merchant/*`

Consumer — `/api/consumer/*`

Payroll — `/api/payroll/*`