Api Basics

Before You Start

Read the following guides before proceeding:

Guide	Why
Environments	API base URLs per environment

Required Headers

Mandatory Headers

The following header is required for all API requests:

Header	Value	Description
`X-Chain-Id`	Chain ID	Target blockchain identifier

Common Headers

Header	Value	When Required
`Authorization`	`Bearer <token>`	Most endpoints (see auth flow)
`Content-Type`	`application/json`	Requests with JSON body

Auth-Specific Headers

Depending on the authentication flow, additional headers may be required. See Authentication
for the flows and Auth Tokens for every token type and what it unlocks.

API Versions

Prefix	Contents
`/api/v1/`	The base surface — authentication, users, KYC, wallets, cards, bank accounts, recipients, activity
`/api/v2/`	Card issuance with a `delivery_id` invoice, recipient creation and update with payment details in one call, `[V2] Get user` and `[V2] Server-side create user`, KYC data update, and the activity feed, search and single-item reads
`/api/v3/`	Corridor transfers — one estimate/initiate/confirm flow covering every payment rail

A v2 endpoint does not deprecate its v1 counterpart. Both remain callable; pick one flow per
integration and follow it end to end.

Pagination

List endpoints take the same query parameters:

Parameter	Description
`page_number`	1-indexed page number
`page_size`	Page size. Defaults to 25 when omitted; maximum 50
`sort`	`name` for ascending name order (default), or `usage` for descending usage count

A page_size above 50 is rejected with 400 ErrorInvalidField and page size exceeds maximum allowed,
carrying max: 50 in error_details.

Amounts

Money crosses the API in two forms, and every estimate response carries both:

Form	Meaning
`amount`	A decimal number in the currency's or token's own precision, e.g. `109.41123037`
`precise_amount`	A string holding the integer amount in the token's smallest unit, e.g. `"109411230370000000000"`

Use precise_amount for on-chain transfers. The exponent is the token's own decimals, not a fixed
18 — read it from GET /api/v1/config/tokens. WUSD and WEUR are 18-decimal, so their smallest unit is
wei; USDC, USDT and EURC are 6-decimal on Base, so "10050000" is 10.05, not a fraction of a cent.
Assuming wei for a 6-decimal token overstates the amount by a factor of 10¹².

See Environments for the token catalogue.

Network Requirements

HTTPS

All API requests require HTTPS
TLS 1.2+ required
Validate SSL certificates in production

IP Allowlisting

S2S token exchange endpoint:
IP allowlisting is available for the POST /api/v1/token endpoint. Contact Wirex to configure allowed IPs for your credentials.

Wirex webhooks to your endpoints:
If you need to allowlist Wirex IPs for incoming webhook requests, contact Wirex to obtain the list of webhook source IPs.

Timeouts

Recommended request timeouts:

API requests: 30 seconds
Webhook delivery: Wirex uses 10 second timeout

Webhooks

Wirex sends webhook notifications for state changes. Webhook URLs are configured by Wirex during onboarding.

Provide your webhook base URL (HTTPS) during onboarding. Wirex will configure the endpoints for your company.

See Webhooks for endpoint paths, payload formats, and implementation details.