Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.baanx.com/llms.txt

Use this file to discover all available pages before exploring further.

Baanx Logo

​
The Complete Platform for Crypto-to-Card Finance

Baanx API is a multi-tenant gateway that bridges cryptocurrency wallets with traditional card payments. Whether you’re building a neobank, crypto exchange, or DeFi platform, our API provides everything you need to offer seamless financial services to your users.

OAuth 2.0 with PKCE

Secure authorization flow with hosted UI or custom authentication

Dual Wallet Models

Custodial (platform-managed) and non-custodial (user-controlled) options

Physical & Virtual Cards

Issue and manage debit cards linked to crypto wallets

Blockchain Delegation

Grant spending authority while maintaining full custody on EVM and Solana

Consent Management

GDPR/CCPA-compliant consent tracking with complete audit trails

​
What Can You Build?

Crypto Wallet Apps

Build wallets with integrated card payments for seamless crypto-to-fiat conversion

DeFi Platforms

Enable users to spend crypto with cards while maintaining self-custody

Neobanks

Launch digital banks with crypto backing and traditional card rails

Exchange Integrations

Add card services to your crypto exchange with custodial wallets

Third-party Apps

Integrate with existing Baanx accounts using OAuth 2.0

Payment Solutions

Create innovative payment experiences combining crypto and cards

​
Choose Your Integration Path

Building with Baanx requires two key decisions:

​
Step 1: OAuth Implementation Mode

Choose how your users will authenticate:

OAuth API Mode (Recommended)

Full control over authentication UX
  • ✅ Custom branded login experience
  • ✅ Native mobile app integration
  • ✅ Complete UI control
  • ✅ Headless/API-first systems
  • ❌ More integration steps (5 vs 4)
  • ❌ You handle user credentials
Best for: Mobile apps, custom UX, white-label solutions

OAuth Hosted UI

Quick setup with pre-built login
  • ✅ Fastest implementation (~30 min)
  • ✅ No credential handling
  • ✅ Built-in security
  • ✅ Perfect for web apps
  • ❌ Standard UI (limited branding)
  • ❌ Requires redirect flow
Best for: Web apps, MVP/prototyping, third-party integrations
Recommendation: Start with API Mode if you need custom UX or building mobile apps. Use Hosted UI only for quick web integrations or when custom auth UI isn’t required.

​
Step 2: Wallet Model

Choose how keys are managed (independent of OAuth choice):

Custodial Wallets

Platform manages keys
  • ✅ Simpler integration
  • ✅ No wallet software needed
  • ✅ Direct card linking
  • ✅ Whitelist-based security
  • ❌ Platform custody required
  • ❌ Limited withdrawal flexibility
Best for: Exchanges, neobanks, mainstream fintech apps, users new to crypto

Non-Custodial Wallets

Users control their own keys
  • ✅ True self-custody
  • ✅ On-chain verification
  • ✅ Flexible withdrawals
  • ✅ DeFi-native approach
  • ❌ More complex setup
  • ❌ Requires wallet software (MetaMask, Phantom)
  • ❌ Delegation flow needed
Best for: DeFi platforms, Web3 apps, crypto-native users, self-custody requirement
Understanding the relationship: OAuth handles authentication (who the user is), while the wallet model handles key custody (who controls the crypto). All integrations use OAuth - you just pick the mode and wallet model that fits your use case.

Mobile App with Custodial Wallets

Example: Crypto exchange mobile app with card issuanceYour choices:
  • OAuth: API Mode (custom login UI in your app)
  • Wallet: Custodial (you manage keys, users get simplicity)
1

Implement OAuth API Mode

Follow API Mode guide for custom login flow
2

Set Up Custodial Wallets

Learn about platform-managed wallets
3

Link Cards to Wallets

Enable card linking
4

Issue Cards

Use card operations to order cards
Implementation time: ~4 hours
Example: DeFi platform where users control their keysYour choices:
  • OAuth: Hosted UI (quick web integration)
  • Wallet: Non-Custodial (users maintain custody via MetaMask/Phantom)
1

Implement OAuth Hosted UI

Follow Hosted UI guide for redirect flow
2

Understand Non-Custodial Model

Review non-custodial wallets
3

Implement Delegation Flow

Follow delegation guide
4

Choose Blockchain

Integrate EVM or Solana
Implementation time: ~4 hours
Example: Digital bank with white-label crypto cardsYour choices:
  • OAuth: API Mode (fully branded experience)
  • Wallet: Custodial (platform security, user simplicity)
1

Set Up OAuth API Mode

Implement API Mode with your branding
2

Configure Custodial Wallets

Set up internal wallets
3

Link and Issue Cards

Enable card operations
Implementation time: ~3 hours
Example: Partner app accessing user accountsYour choices:
  • OAuth: Hosted UI (simplest, most secure for third parties)
  • Wallet: Depends on the main platform’s configuration
1

Understand OAuth Flow

Learn OAuth 2.0 with PKCE
2

Implement Hosted UI

Follow Hosted UI guide
3

Make API Calls

Use access tokens to fetch user data
Implementation time: ~30 minutes

Start with OAuth Quickstart

Get up and running quickly
Perfect for: Evaluating Baanx for your use caseStart with these high-level overviews:

OAuth Options

API Mode vs Hosted UI - understand the differences

Wallet Models

Custodial vs non-custodial - choose based on your users

Card Capabilities

Physical/virtual cards, PIN management, transactions

Delegation Flow

How non-custodial users spend crypto with cards
New to crypto integration? We recommend starting with OAuth API Mode + Custodial Wallets for the best balance of control and simplicity.

​
Key Features

​
Flexible Authentication

OAuth 2.0 with PKCE

Industry-standard authorization for third-party integrations with hosted UI or custom flows

Direct Login API

Traditional username/password authentication for first-party applications

​
Wallet Options for Every Use Case

Custodial Wallets

Platform manages keys - Simpler integration, built-in security, whitelist-based withdrawals, direct card linkingLearn more →

Non-Custodial Wallets

Users control keys - True self-custody, blockchain delegation, multi-wallet support, on-chain verificationLearn more →

​
Card Management

Physical & Virtual Cards

Issue both physical and virtual debit cards

Secure Access

One-time tokens for viewing sensitive card details

PIN Management

Users can view and set PINs securely

Transaction History

Real-time transaction tracking and statements

Card Controls

Freeze/unfreeze cards, manage limits

Status Tracking

Monitor activation, delivery, and usage

​
Blockchain Delegation

EVM Chains

Support for Linea and Ethereum networks with smart contract delegation

Solana

Native Solana integration with signature-based proof of ownership

Regulatory Compliance

GDPR, CCPA, and E-Sign Act compliance with immutable audit trails for all consent changes

Flexible Policies

US and Global policy types with region-specific requirements (eSignAct for US users)

Complete Audit Trail

Track all consent changes with timestamps, IP addresses, and user agent information

User Control

Allow users to grant, deny, and revoke consent for marketing, SMS, and email notifications

​
Multi-Tenant Architecture

The Baanx API automatically routes requests to your environment based on your credentials. Each client receives unique keys for sandbox and production environments.
Required on ALL requests: Include the x-client-key header in every API call for proper routing. Missing this header results in a 499 status code.

​
Required Headers

HeaderRequiredPurpose
x-client-keyAlwaysYour public API key - identifies your tenant
AuthorizationAuthenticated endpointsBearer token for user context
x-secret-keyOAuth endpoints onlySecret key for client authentication
x-us-envOptionalSet to true for US region routing

​
Why Developers Choose Baanx

Flexibility

Choose custodial or non-custodial models based on your business needs and user preferences

Security First

OAuth 2.0 with PKCE, multi-tenant isolation, one-time tokens, and blockchain verification

Developer Experience

Clear documentation, OpenAPI specification, practical examples, and responsive support

Production Ready

Battle-tested infrastructure handling real card transactions and blockchain operations

API Mode + Custodial

Mobile apps, neobanks, exchangesCustom UX with platform-managed keysOAuth: API Mode | Wallet: CustodialTime: ~4 hours

Hosted UI + Custodial

Web apps, quick integrationsFast setup with platform securityOAuth: Hosted UI | Wallet: CustodialTime: ~2 hours

API Mode + Non-Custodial

DeFi mobile apps, Web3 walletsCustom UX with user-controlled keysOAuth: API Mode | Wallet: Non-CustodialTime: ~6 hours

Hosted UI + Non-Custodial

DeFi web platformsQuick OAuth setup with self-custodyOAuth: Hosted UI | Wallet: Non-CustodialTime: ~4 hours

​
Explore the Documentation

Conceptual documentation organized by domain

Browse All Guides

Start with conceptual documentation

​
Getting Started Checklist

1

Get API Credentials

Contact your account manager to receive your x-client-key and x-secret-key for sandbox and production
2

Choose OAuth Implementation Mode

Select API Mode (custom UX) or Hosted UI (quick setup) based on your authentication needs
3

Choose Wallet Model

Select Custodial (platform-managed) or Non-Custodial (user-controlled) based on your custody model
4

Implement Authentication

Follow the OAuth guide for your chosen mode to set up user authentication
5

Set Up Consent Management

Implement Consent Management to track user consent for GDPR, CCPA, and E-Sign Act compliance. Consent collection is required during user registration before accessing card or wallet features.
6

Test in Sandbox

Use your sandbox credentials to test the full integration before going live, including consent collection flows
7

Go to Production

Schedule an operational “go live” meeting with your account manager to review your integration and initiate the approval process for production credentials

​
Need Help?

Integration Support

Contact your technical account manager for implementation assistance

API Issues

Check troubleshooting guides or contact support at support@baanx.com

OpenAPI Spec

Download the complete OpenAPI 3.1 specification for your tools
Ready to get started? Most developers begin with the OAuth Quickstart to understand authentication, then move to their specific use case (wallets, cards, or delegation).