> ## 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.

# Welcome to Baanx API

> Build powerful financial applications with cryptocurrency wallets and card payments

<img className="block dark:hidden" src="https://mintcdn.com/baanxgroup/UMFEbgIKXSxGsjxl/logo/baanx.webp?fit=max&auto=format&n=UMFEbgIKXSxGsjxl&q=85&s=f10e1a3c5e0b14e168a8f948a291128b" alt="Baanx Logo" height="100" data-path="logo/baanx.webp" />

<img className="hidden dark:block" src="https://mintcdn.com/baanxgroup/UMFEbgIKXSxGsjxl/logo/baanx.webp?fit=max&auto=format&n=UMFEbgIKXSxGsjxl&q=85&s=f10e1a3c5e0b14e168a8f948a291128b" alt="Baanx Logo" height="100" data-path="logo/baanx.webp" />

## 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.

<CardGroup cols={2}>
  <Card title="OAuth 2.0 with PKCE" icon="shield-check" color="#16A34A">
    Secure authorization flow with hosted UI or custom authentication
  </Card>

  <Card title="Dual Wallet Models" icon="wallet" color="#0052CA">
    Custodial (platform-managed) and non-custodial (user-controlled) options
  </Card>

  <Card title="Physical & Virtual Cards" icon="credit-card" color="#16A34A">
    Issue and manage debit cards linked to crypto wallets
  </Card>

  <Card title="Blockchain Delegation" icon="link" color="#0052CA">
    Grant spending authority while maintaining full custody on EVM and Solana
  </Card>

  <Card title="Consent Management" icon="clipboard-check" color="#16A34A">
    GDPR/CCPA-compliant consent tracking with complete audit trails
  </Card>
</CardGroup>

## What Can You Build?

<CardGroup cols={3}>
  <Card title="Crypto Wallet Apps" icon="mobile" href="/guides/wallet/overview">
    Build wallets with integrated card payments for seamless crypto-to-fiat conversion
  </Card>

  <Card title="DeFi Platforms" icon="chart-line" href="/guides/delegation/overview">
    Enable users to spend crypto with cards while maintaining self-custody
  </Card>

  <Card title="Neobanks" icon="building-columns" href="/guides/card/overview">
    Launch digital banks with crypto backing and traditional card rails
  </Card>

  <Card title="Exchange Integrations" icon="arrow-right-arrow-left" href="/guides/wallet/custodial/index">
    Add card services to your crypto exchange with custodial wallets
  </Card>

  <Card title="Third-party Apps" icon="plug" href="/guides/oauth/quickstart">
    Integrate with existing Baanx accounts using OAuth 2.0
  </Card>

  <Card title="Payment Solutions" icon="credit-card" href="/guides/card/management">
    Create innovative payment experiences combining crypto and cards
  </Card>
</CardGroup>

## Choose Your Integration Path

Building with Baanx requires two key decisions:

### Step 1: OAuth Implementation Mode

Choose how your users will authenticate:

<CardGroup cols={2}>
  <Card title="OAuth API Mode (Recommended)" icon="code">
    **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
  </Card>

  <Card title="OAuth Hosted UI" icon="browser">
    **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
  </Card>
</CardGroup>

<Tip>
  **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.
</Tip>

### Step 2: Wallet Model

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

<CardGroup cols={2}>
  <Card title="Custodial Wallets" icon="building-shield">
    **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
  </Card>

  <Card title="Non-Custodial Wallets" icon="key">
    **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
  </Card>
</CardGroup>

<Note>
  **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.
</Note>

***

<AccordionGroup>
  <Accordion title="Mobile App with Custodial Wallets" icon="mobile" defaultOpen>
    **Example:** Crypto exchange mobile app with card issuance

    **Your choices:**

    * OAuth: **API Mode** (custom login UI in your app)
    * Wallet: **Custodial** (you manage keys, users get simplicity)

    <Steps>
      <Step title="Implement OAuth API Mode">
        Follow [API Mode guide](/guides/oauth/api-mode) for custom login flow
      </Step>

      <Step title="Set Up Custodial Wallets">
        Learn about [platform-managed wallets](/guides/wallet/custodial/index)
      </Step>

      <Step title="Link Cards to Wallets">
        Enable [card linking](/guides/wallet/custodial/card-linking)
      </Step>

      <Step title="Issue Cards">
        Use [card operations](/guides/card/overview) to order cards
      </Step>
    </Steps>

    **Implementation time:** \~4 hours
  </Accordion>

  <Accordion title="Web App with DeFi Self-Custody" icon="chart-line">
    **Example:** DeFi platform where users control their keys

    **Your choices:**

    * OAuth: **Hosted UI** (quick web integration)
    * Wallet: **Non-Custodial** (users maintain custody via MetaMask/Phantom)

    <Steps>
      <Step title="Implement OAuth Hosted UI">
        Follow [Hosted UI guide](/guides/oauth/hosted-ui) for redirect flow
      </Step>

      <Step title="Understand Non-Custodial Model">
        Review [non-custodial wallets](/guides/wallet/non-custodial/index)
      </Step>

      <Step title="Implement Delegation Flow">
        Follow [delegation guide](/guides/delegation/implementation)
      </Step>

      <Step title="Choose Blockchain">
        Integrate [EVM](/guides/delegation/evm-chains) or [Solana](/guides/delegation/solana)
      </Step>
    </Steps>

    **Implementation time:** \~4 hours
  </Accordion>

  <Accordion title="Neobank with Custom UX + Platform Custody" icon="building-columns">
    **Example:** Digital bank with white-label crypto cards

    **Your choices:**

    * OAuth: **API Mode** (fully branded experience)
    * Wallet: **Custodial** (platform security, user simplicity)

    <Steps>
      <Step title="Set Up OAuth API Mode">
        Implement [API Mode](/guides/oauth/api-mode) with your branding
      </Step>

      <Step title="Configure Custodial Wallets">
        Set up [internal wallets](/guides/wallet/custodial/index)
      </Step>

      <Step title="Link and Issue Cards">
        Enable [card operations](/guides/card/overview)
      </Step>
    </Steps>

    **Implementation time:** \~3 hours
  </Accordion>

  <Accordion title="Third-Party Integration (OAuth Only)" icon="plug">
    **Example:** Partner app accessing user accounts

    **Your choices:**

    * OAuth: **Hosted UI** (simplest, most secure for third parties)
    * Wallet: Depends on the main platform's configuration

    <Steps>
      <Step title="Understand OAuth Flow">
        Learn [OAuth 2.0 with PKCE](/guides/oauth/quickstart)
      </Step>

      <Step title="Implement Hosted UI">
        Follow [Hosted UI guide](/guides/oauth/hosted-ui)
      </Step>

      <Step title="Make API Calls">
        Use access tokens to [fetch user data](/api-reference/user/get-user)
      </Step>
    </Steps>

    **Implementation time:** \~30 minutes

    <Card title="Start with OAuth Quickstart" icon="rocket" href="/guides/oauth/quickstart">
      Get up and running quickly
    </Card>
  </Accordion>

  <Accordion title="I'm exploring what's possible" icon="compass">
    **Perfect for:** Evaluating Baanx for your use case

    Start with these high-level overviews:

    <CardGroup cols={2}>
      <Card title="OAuth Options" icon="shield" href="/guides/oauth/quickstart">
        API Mode vs Hosted UI - understand the differences
      </Card>

      <Card title="Wallet Models" icon="wallet" href="/guides/wallet/overview">
        Custodial vs non-custodial - choose based on your users
      </Card>

      <Card title="Card Capabilities" icon="credit-card" href="/guides/card/overview">
        Physical/virtual cards, PIN management, transactions
      </Card>

      <Card title="Delegation Flow" icon="link" href="/guides/delegation/overview">
        How non-custodial users spend crypto with cards
      </Card>
    </CardGroup>

    <Note>
      **New to crypto integration?** We recommend starting with **OAuth API Mode + Custodial Wallets** for the best balance of control and simplicity.
    </Note>
  </Accordion>
</AccordionGroup>

## Key Features

### Flexible Authentication

<CardGroup cols={2}>
  <Card title="OAuth 2.0 with PKCE" icon="shield-check">
    Industry-standard authorization for third-party integrations with hosted UI or custom flows
  </Card>

  <Card title="Direct Login API" icon="arrow-right-to-bracket">
    Traditional username/password authentication for first-party applications
  </Card>
</CardGroup>

### Wallet Options for Every Use Case

<CardGroup cols={2}>
  <Card title="Custodial Wallets" icon="building-shield">
    **Platform manages keys** - Simpler integration, built-in security, whitelist-based withdrawals, direct card linking

    [Learn more →](/guides/wallet/custodial/index)
  </Card>

  <Card title="Non-Custodial Wallets" icon="user-shield">
    **Users control keys** - True self-custody, blockchain delegation, multi-wallet support, on-chain verification

    [Learn more →](/guides/wallet/non-custodial/index)
  </Card>
</CardGroup>

### Card Management

<CardGroup cols={3}>
  <Card title="Physical & Virtual Cards" icon="credit-card">
    Issue both physical and virtual debit cards
  </Card>

  <Card title="Secure Access" icon="lock">
    One-time tokens for viewing sensitive card details
  </Card>

  <Card title="PIN Management" icon="hashtag">
    Users can view and set PINs securely
  </Card>

  <Card title="Transaction History" icon="clock-rotate-left">
    Real-time transaction tracking and statements
  </Card>

  <Card title="Card Controls" icon="toggle-on">
    Freeze/unfreeze cards, manage limits
  </Card>

  <Card title="Status Tracking" icon="signal">
    Monitor activation, delivery, and usage
  </Card>
</CardGroup>

### Blockchain Delegation

<CardGroup cols={2}>
  <Card title="EVM Chains" icon="ethereum">
    Support for Linea and Ethereum networks with smart contract delegation
  </Card>

  <Card title="Solana" icon="s">
    Native Solana integration with signature-based proof of ownership
  </Card>
</CardGroup>

### Consent Management

<CardGroup cols={2}>
  <Card title="Regulatory Compliance" icon="scale-balanced">
    GDPR, CCPA, and E-Sign Act compliance with immutable audit trails for all consent changes
  </Card>

  <Card title="Flexible Policies" icon="globe">
    US and Global policy types with region-specific requirements (eSignAct for US users)
  </Card>

  <Card title="Complete Audit Trail" icon="clock-rotate-left">
    Track all consent changes with timestamps, IP addresses, and user agent information
  </Card>

  <Card title="User Control" icon="user-check">
    Allow users to grant, deny, and revoke consent for marketing, SMS, and email notifications
  </Card>
</CardGroup>

## 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.

<Warning>
  **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.
</Warning>

### Required Headers

| Header          | Required                | Purpose                                      |
| --------------- | ----------------------- | -------------------------------------------- |
| `x-client-key`  | **Always**              | Your public API key - identifies your tenant |
| `Authorization` | Authenticated endpoints | Bearer token for user context                |
| `x-secret-key`  | OAuth endpoints only    | Secret key for client authentication         |
| `x-us-env`      | Optional                | Set to `true` for US region routing          |

## Why Developers Choose Baanx

<CardGroup cols={2}>
  <Card title="Flexibility" icon="sliders">
    Choose custodial or non-custodial models based on your business needs and user preferences
  </Card>

  <Card title="Security First" icon="shield-halved">
    OAuth 2.0 with PKCE, multi-tenant isolation, one-time tokens, and blockchain verification
  </Card>

  <Card title="Developer Experience" icon="code">
    Clear documentation, OpenAPI specification, practical examples, and responsive support
  </Card>

  <Card title="Production Ready" icon="check">
    Battle-tested infrastructure handling real card transactions and blockchain operations
  </Card>
</CardGroup>

## Popular Integration Combinations

<CardGroup cols={2}>
  <Card title="API Mode + Custodial" icon="mobile" href="/guides/oauth/api-mode">
    **Mobile apps, neobanks, exchanges**

    Custom UX with platform-managed keys

    OAuth: API Mode | Wallet: Custodial

    **Time:** \~4 hours
  </Card>

  <Card title="Hosted UI + Custodial" icon="globe" href="/guides/oauth/hosted-ui">
    **Web apps, quick integrations**

    Fast setup with platform security

    OAuth: Hosted UI | Wallet: Custodial

    **Time:** \~2 hours
  </Card>

  <Card title="API Mode + Non-Custodial" icon="shield" href="/guides/delegation/implementation">
    **DeFi mobile apps, Web3 wallets**

    Custom UX with user-controlled keys

    OAuth: API Mode | Wallet: Non-Custodial

    **Time:** \~6 hours
  </Card>

  <Card title="Hosted UI + Non-Custodial" icon="link" href="/guides/delegation/overview">
    **DeFi web platforms**

    Quick OAuth setup with self-custody

    OAuth: Hosted UI | Wallet: Non-Custodial

    **Time:** \~4 hours
  </Card>
</CardGroup>

## Explore the Documentation

<Tabs>
  <Tab title="Guides">
    **Conceptual documentation organized by domain**

    * [OAuth 2.0 & Authentication](/guides/oauth/quickstart) - Secure authorization flows
    * [User Management](/guides/user/overview) - Registration, profiles, verification
    * [Consent Management](/guides/consent/overview) - GDPR/CCPA-compliant consent tracking
    * [Wallet Management](/guides/wallet/overview) - Custodial and non-custodial options
    * [Non-Custodial Delegation](/guides/delegation/overview) - Blockchain delegation flows
    * [Card Operations](/guides/card/overview) - Card issuance and management

    <Card title="Browse All Guides" icon="book-open" href="/guides/oauth/quickstart">
      Start with conceptual documentation
    </Card>
  </Tab>

  <Tab title="API Reference">
    **Complete endpoint documentation with examples**

    * [Authentication Endpoints](/api-reference/auth/oauth-authorize-initiate) - OAuth and login APIs
    * [User Endpoints](/api-reference/user/get-user) - User data and verification
    * [Card Endpoints](/api-reference/card/order) - Card operations and management
    * [Wallet Endpoints](/api-reference/wallet/credit) - Wallet operations and withdrawals
    * [Delegation Endpoints](/api-reference/delegation/token) - Blockchain delegation

    <Card title="Browse API Reference" icon="code" href="/api-reference/introduction">
      Detailed endpoint documentation
    </Card>
  </Tab>
</Tabs>

## Getting Started Checklist

<Steps>
  <Step title="Get API Credentials">
    Contact your account manager to receive your `x-client-key` and `x-secret-key` for sandbox and production
  </Step>

  <Step title="Choose OAuth Implementation Mode">
    Select [API Mode](/guides/oauth/api-mode) (custom UX) or [Hosted UI](/guides/oauth/hosted-ui) (quick setup) based on your authentication needs
  </Step>

  <Step title="Choose Wallet Model">
    Select [Custodial](/guides/wallet/custodial/index) (platform-managed) or [Non-Custodial](/guides/wallet/non-custodial/index) (user-controlled) based on your custody model
  </Step>

  <Step title="Implement Authentication">
    Follow the [OAuth guide](/guides/oauth/quickstart) for your chosen mode to set up user authentication
  </Step>

  <Step title="Set Up Consent Management">
    Implement [Consent Management](/guides/consent/overview) 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.
  </Step>

  <Step title="Test in Sandbox">
    Use your sandbox credentials to test the full integration before going live, including consent collection flows
  </Step>

  <Step title="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
  </Step>
</Steps>

## Need Help?

<CardGroup cols={3}>
  <Card title="Integration Support" icon="headset">
    Contact your technical account manager for implementation assistance
  </Card>

  <Card title="API Issues" icon="bug">
    Check [troubleshooting guides](/guides/oauth/troubleshooting) or contact support at [support@baanx.com](mailto:support@baanx.com)
  </Card>

  <Card title="OpenAPI Spec" icon="file-code" href="/api-reference/openapi.json">
    Download the complete OpenAPI 3.1 specification for your tools
  </Card>
</CardGroup>

<Note>
  **Ready to get started?** Most developers begin with the [OAuth Quickstart](/guides/oauth/quickstart) to understand authentication, then move to their specific use case (wallets, cards, or delegation).
</Note>