Wirex baas overview

Wirex BaaS Platform Overview

Introduction

Wirex BaaS (Banking-as-a-Service) is a blockchain-native financial services platform that enables partners to embed comprehensive financial capabilities into their applications through REST APIs. The platform bridges traditional finance and decentralized infrastructure, providing a unified interface for:

• Account Abstraction (AA) Wallets -- Smart contract wallets deployed on-chain with gasless transactions, social recovery, and multi-signature support. Each user gets a deterministic wallet address derived from their identity.
• KYC Verification -- Identity verification flows supporting document checks, liveness detection, and regulatory compliance across 88+ countries. Powered by third-party providers with webhook-based status updates.
• Visa Card Issuance -- Virtual and physical Visa card provisioning, lifecycle management, transaction controls, and Apple Pay / Google Pay tokenization. Cards are funded from user wallets.
• Crypto Asset Management -- Multi-chain token support (USDC, USDT, EURC, WUSD, WEUR) with on-chain balances, transfers, and exchange operations across Base and Stellar networks.
• Fiat Banking (SEPA/ACH) -- Bank account creation, inbound/outbound transfers, and currency conversion. SEPA covers 28 European countries; ACH covers 34+ countries including all US states.

All services are accessed through a consistent REST API layer with OAuth2 authentication, standardized error handling, and blockchain transaction management.

---

Integration Flow

Integrating with Wirex BaaS follows five sequential steps:

Step 1: Partner Setup

Wirex provisions your partner account and issues credentials:

• client_id -- UUID identifying your application
• client_secret -- Secret string for OAuth2 token exchange
• partner_id -- 16-byte hex identifier used in on-chain operations (e.g., 0x00000000000000000000000000000007)

You receive access to the Sandbox environment for development and testing.

Step 2: Authentication

Establish server-to-server authentication using OAuth2 client credentials:

POST /api/v1/token
Content-Type: application/json

{
  "client_id": "<your-client-id>",
  "client_secret": "<your-client-secret>",
  "grant_type": "client_credentials"
}

The returned access_token is valid for 48 hours and is required as a Bearer token on all subsequent API calls.

Step 3: On-Chain Configuration

Configure your on-chain environment:

1. Query the Contract Registry to discover deployed contract addresses (Accounts, FundsManagement, ExecutionDelayPolicy, TokensRegistry).
2. Verify token addresses and decimals from the TokensRegistry contract.
3. Set up webhook endpoints for asynchronous event notifications (transaction confirmations, KYC status changes, card events).

Step 4: API Registration

Register your first user through the API:

1. Call POST /api/v1/user or POST /api/v2/user to create a user record.
2. The platform deploys an Account Abstraction wallet on the configured chain.
3. Obtain a user-scoped token via POST /api/v1/user/authorize for user-specific operations.

Step 5: Operations

With authentication and user registration complete, you can:

• Initiate KYC verification flows
• Issue virtual or physical Visa cards
• Execute crypto transfers and exchanges
• Create bank accounts and process fiat transfers
• Query balances, transactions, and account status

---

Environments

Wirex BaaS provides separate environments for development and production use.

Core API Environments

Environment	Base URL	Purpose
Sandbox	https://api-baas.wirexapp.tech	Development and testing with test data
Production	https://api-baas.wirexapp.com	Live operations with real funds

PCI-Compliant Card Environments

Card-related operations that handle sensitive PAN data use dedicated PCI DSS-compliant endpoints, specifically for card tokenization in push-to-card transfers:

Environment	Base URL	Purpose
PCI Sandbox	https://wx-acquiring-card-manager-uat.wirexapp.com	Card testing
PCI Production	https://wx-acquiring-card-manager.wirexapp.com	Live card operations

Helper API

Environment	Base URL	Purpose
Helper API	https://ramc.wirexapp.tech	Utility services and auxiliary operations

Blockchain Networks

Wirex BaaS operates on the following blockchain networks:

Production Networks:

Network	Chain ID	Description
Base	8453	Ethereum L2 (Coinbase) -- primary EVM chain
Stellar	9223372036854775806	Stellar network for cross-border payments

Sandbox Networks:

Network	Chain ID	Description
Base Sepolia	84532	Base testnet for development
Stellar Testnet	9223372036854775806	Stellar testnet (same chain ID as production)

Note: The Stellar chain ID is the same value (9223372036854775806) in both sandbox and production. The environment base URL determines which Stellar network is used.

---

Credentials

Partners receive three credentials upon onboarding:

Credential	Format	Description
client_id	UUID string	Uniquely identifies your partner application. Passed in the token request body.
client_secret	Opaque string	Used alongside client_id to authenticate token requests. Must be stored securely and never exposed in client-side code.
partner_id	16-byte hex string	On-chain identifier for your partner account (e.g., 0x00000000000000000000000000000007). Used as the parentEntity parameter when registering user wallets in the Accounts smart contract, and in some API headers. Not secret but should be validated against expected value. Can be stored in application configuration.

Security Requirements

• Store client_secret in a secrets manager or encrypted environment variable. Never commit it to source control.
• Rotate credentials immediately if a compromise is suspected.
• Use separate credentials for Sandbox and Production environments.

---

API Basics

Protocol and Security

• HTTPS only -- All API communication uses HTTPS with TLS 1.2 or higher. Plain HTTP requests are rejected.
• Content-Type -- All request and response bodies use application/json.
• Timeout -- A 30-second timeout is recommended for all API calls. Some blockchain operations may take longer; use webhooks for async confirmation.

Required Headers

Every API request must include the following headers:

Header	Required	Description
Authorization	Yes	Bearer token from /api/v1/token (e.g., Bearer eyJhbGciOi...)
X-Chain-Id	Yes	Blockchain network identifier. Must match your target chain (e.g., 84532 for Sandbox Base Sepolia, 8453 for Production Base). Required for all requests.
Content-Type	Yes (for POST/PUT)	application/json

Additional headers for user-specific operations:

Header	When Required	Description
X-User-Address	User-specific calls	User's EOA (Externally Owned Account) address — NOT the Smart Wallet address
X-User-Email	User-specific calls	Email address of the user
X-User-Id	User-specific calls	Internal user identifier

Exactly one of X-User-Address, X-User-Email, or X-User-Id is required for endpoints that operate on a specific user. Providing multiple user identity headers in the same request is rejected with an error. User-agnostic endpoints (token, config, user creation) do not require these headers.

User-Agnostic Endpoints

The following endpoints do not require user identity headers:

• POST /api/v1/token -- Authentication
• POST /api/v1/user -- User creation
• POST /api/v2/user -- User creation (v2)
• GET /api/v1/config -- Platform configuration
• GET /api/v1/validation/rules -- Validation rules

---

MCP Server

Wirex BaaS provides a Model Context Protocol (MCP) server for AI-assisted development. The MCP server gives AI tools direct access to API documentation, endpoint specifications, and code generation assistance.

MCP Server URL: https://docs.wirexapp.com/mcp

The MCP server supports:

• API Documentation Access -- Query endpoint specifications, request/response schemas, and usage examples.
• Documentation Search -- Search across the full Wirex BaaS documentation corpus.
• Real-Time Data -- Access current API status, supported tokens, and configuration values.
• Code Generation Assistance -- Generate integration code snippets for common workflows.

For detailed setup instructions across different tools (Claude Code, Cursor, Claude Desktop, Windsurf), see the MCP Setup Reference.

---

Supported Countries

Wirex BaaS supports operations in 77 countries across five regions:

Region	Country Count	Examples
Europe	35	United Kingdom, Germany, France, Spain, Italy, Netherlands, Sweden, Switzerland, Poland, Austria, and 25 more
Asia-Pacific	10	Singapore, Japan, Hong Kong, Australia, Indonesia, Malaysia, Taiwan, Thailand, Vietnam, and more
Latin America	7	Brazil, Mexico, Argentina, Chile, Colombia, Peru, Ecuador
Rest of World	24	UAE, South Africa, Israel, Turkey, Nigeria, Saudi Arabia, South Korea, and 17 more
United States	1	Full coverage across all 50 states + DC

For the complete list with ISO country codes, see the Supported Regions Reference.

Bank Account Availability

Fiat banking services are available through two networks:

• SEPA (Single Euro Payments Area) -- 28 European countries. Supports EUR-denominated transfers with T+1 settlement.
• ACH (Automated Clearing House) -- 34+ countries including all US states and territories. Supports USD-denominated transfers.

Availability depends on the user's country of residence and completed KYC level.

---

Error Handling

All API errors follow a consistent JSON format:

{
  "error_reason": "ErrorInvalidField",
  "error_description": "The provided X-Chain-Id header value is not supported.",
  "error_category": {
    "category": "CategoryValidationFailure",
    "http_status_code": 400
  },
  "error_details": [
    { "key": "field", "details": "X-Chain-Id" },
    { "key": "issue", "details": "unsupported_value" }
  ]
}

Error Fields

Field	Type	Description
error_reason	string	PascalCase error code (e.g., ErrorInvalidField, ErrorPermissionDenied, ErrorNotFound, ErrorExpired, ErrorMissingField, ErrorAlreadyExists, ErrorNotSupported, ErrorConfigurationInvalid)
error_description	string	Human-readable explanation of the error
error_category	object	Error classification object containing category (string) and http_status_code (integer)
error_details	array	Array of objects, each with key (string) and details (string) providing additional context

Error Categories

Category	HTTP Status	Description	Recommended Action
CategoryValidationFailure	400	Invalid request parameters, missing headers, malformed data	Fix the request and retry
CategoryUnauthorized	401	Invalid or expired token, insufficient permissions	Re-authenticate and retry
CategoryInternalFailure	500	Server-side error	Retry with exponential backoff; contact support if persistent
CategoryTransientFailure	429	Rate limit exceeded or temporary service degradation	Retry after the delay indicated in Retry-After header

Error Handling Best Practices

1. Always check the error_category to determine retry strategy.
2. Implement exponential backoff for CategoryTransientFailure and CategoryInternalFailure errors.
3. Do not retry CategoryValidationFailure errors without modifying the request.
4. Refresh tokens proactively -- cache tokens and refresh 5 minutes before expiry to avoid CategoryUnauthorized errors.
5. Log error_reason and error_description for debugging and support escalations.

---

References

• Environments Reference -- Full environment URLs, chain IDs, contract addresses, and token configurations
• MCP Setup Reference -- MCP server configuration for all supported AI tools
• Supported Regions Reference -- Complete country list with ISO codes and bank availability