Skip to main content

​
Welcome to the Baanx API

The Baanx API is a comprehensive multi-tenant gateway that enables financial applications with OAuth 2.0 authentication, card management, cryptocurrency wallet operations, and blockchain delegation capabilities. This API reference provides detailed documentation for all endpoints, including request/response schemas, authentication requirements, and practical examples.

Getting Started

Learn how to authenticate and make your first API call

OpenAPI Specification

Download the complete OpenAPI 3.1 specification

Guides

Step-by-step integration guides for common workflows

Troubleshooting

Common issues and solutions

​
Core Capabilities

Secure authorization flow with PKCE support, enabling third-party applications to access user accounts safely. Supports both hosted UI and custom authentication modes.Key Features:
  • Authorization Code Flow with PKCE
  • Hosted UI for simplified integration
  • API mode for custom authentication UX
  • Refresh token support (184-day expiry)
  • Session management and token revocation
Complete user lifecycle management including registration, verification, profile management, and settings.Key Features:
  • Multi-step registration with email/phone verification
  • KYC and identity verification
  • Profile and settings management
  • Secure credential handling
Manage physical and virtual debit cards linked to cryptocurrency wallets.Key Features:
  • View card details securely (one-time tokens)
  • PIN management (view and set)
  • Card activation and status control
  • Transaction history and limits
Support for both custodial (platform-managed) and non-custodial (user-controlled) wallet models.Custodial Features:
  • Platform-managed keys and security
  • Direct card linking
  • Whitelist-based withdrawals
  • Multi-currency support
Non-Custodial Features:
  • External wallet registration
  • User maintains custody
  • Priority management for multiple wallets
  • Real-time balance and allowance tracking
Enable non-custodial users to grant spending authority for card payments while maintaining full custody of assets.Key Features:
  • EVM chain support (Linea, Ethereum)
  • Solana support
  • On-chain transaction verification
  • Signature-based proof of ownership
  • Flexible allowance management

​
Multi-Tenant Architecture

The Baanx API automatically routes requests to the appropriate backend environment based on your client credentials. Each integration receives unique keys for sandbox and production environments.
Required on ALL requests: The x-client-key header must be included in every API call for proper routing.

​
Required Headers

HeaderRequiredDescription
x-client-keyYesYour public API key - required on all requests
AuthorizationConditionalBearer token for authenticated endpoints
x-secret-keyConditionalSecret key for OAuth endpoints only
x-us-envOptionalSet to true for US region routing

​
Custom HTTP Status Codes

In addition to standard HTTP status codes, the API uses custom codes for specific scenarios:
  • 498 - Invalid client key (check your x-client-key header)
  • 499 - Missing client key (add x-client-key to request)

​
Authentication

The Baanx API uses Bearer token authentication for protected endpoints. Tokens are obtained through either the OAuth 2.0 flow or direct login.

​
Token Types

Understanding the different token types is critical for proper API integration.
Token TypePurposeLifetimeUsage
JWT TokenOAuth flow session only10 minutesUsed only within authorization flow, not for API calls
Access TokenAPI authentication6 hoursInclude in Authorization: Bearer header for all API requests
Refresh TokenToken renewal184 daysExchange for new access tokens when they expire

​
Getting Access Tokens

POST /v1/auth/login
Content-Type: application/json
x-client-key: YOUR_PUBLIC_KEY

{
  "username": "[email protected]",
  "password": "secure_password"
}

# Response includes access_token
{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
  "expiresIn": 21600
}

​
Using Access Tokens

Include the access token in the Authorization header for all authenticated requests: 
GET /v1/user/me
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
x-client-key: YOUR_PUBLIC_KEY

​
Refreshing Tokens

When your access token expires, use the refresh token to obtain a new one: 
POST /v1/auth/oauth/token
Content-Type: application/json
x-client-key: YOUR_PUBLIC_KEY
x-secret-key: YOUR_SECRET_KEY

{
  "grant_type": "refresh_token",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}

​
Environments

The API supports multiple environments for different use cases:

Production

Live environment with real user data and transactions. Use production credentials for live applications.

Sandbox

Testing environment with isolated data. Use sandbox credentials for development and testing.
Always test your integration thoroughly in the sandbox environment before moving to production.

​
Rate Limiting

The API implements rate limiting to ensure fair usage and system stability. If you exceed rate limits, you’ll receive a 429 Too Many Requests response with a Retry-After header indicating when you can retry.
Contact your account manager for information about rate limits specific to your plan.

​
Error Handling

All error responses follow a consistent format: 
{
  "error": "error_code",
  "error_description": "Human-readable description of what went wrong",
  "details": {
    "field": "Additional context when applicable"
  }
}
Common error scenarios:
  • 400 Bad Request - Invalid request parameters or body
  • 401 Unauthorized - Missing or invalid authentication
  • 403 Forbidden - Valid authentication but insufficient permissions
  • 404 Not Found - Resource does not exist
  • 498 Invalid Client Key - Check your x-client-key header
  • 499 Missing Client Key - Add x-client-key to your request
  • 500 Internal Server Error - Contact support if persistent

​
Getting Help

Integration Guides

Follow step-by-step guides for common integration patterns

Support

Contact your account manager for technical support and questions

​
Next Steps

Ready to get started? Here are some recommended paths:
  1. New to the API? Start with the OAuth Quickstart to understand authentication
  2. Building a card application? Check out Card Operations
  3. Need regulatory compliance? Review Consent Management for GDPR/CCPA requirements
  4. Implementing wallets? Review Wallet Management (custodial) or Delegation Flow (non-custodial)
  5. Testing integration? Review Troubleshooting for common issues