Generate Delegation Token

Overview

This endpoint generates a single-use delegation token required to initiate the wallet delegation flow. This is Step 1 of a 3-step process that allows users to delegate spending authority from their non-custodial wallets to the platform for card payments.

When to Use: Call this endpoint when a user initiates the delegation flow in your application. The returned token is required to finalize delegation in Step 3 after the user completes wallet connection and blockchain approval.

Delegation Workflow

The complete delegation process involves three steps:

Backend (This Endpoint): Request delegation token from API
Frontend (Your Implementation): User connects wallet and approves blockchain transaction
Backend: Submit delegation proof using blockchain-specific endpoint:
- POST /v1/delegation/evm/post-approval for EVM chains (Linea/Ethereum)
- POST /v1/delegation/solana/post-approval for Solana

See the Delegation Guide for complete implementation details.

Authentication

x-client-key

string

required

Your public client key for API authentication

Authorization

string

required

Bearer token format: Bearer {access_token}

Query Parameters

region

string

Region identifier for environment routing. Use us for US-specific Linea routing.Example: ?region=us

Alternatively, you can use the x-us-env: true header instead of the region query parameter.

Response

token

string

required

Single-use delegation token (UUID format). This token is used in Step 3 to finalize the delegation.Characteristics:

Single-use only - becomes invalid after use in POST approval endpoint
~10 minute lifetime - complete the delegation flow before expiration
Must be passed to your frontend for use after wallet connection

nonce

string

required

Unique nonce that must be included in the post-approval request. This nonce links the delegation token request to the final approval submission.Example: 5f8a9b2c4d3e1a7b9c6d8e2fImportant: Store this nonce alongside the token and pass both to your frontend. Both values are required when submitting the delegation proof in Step 3.

curl --request GET \
  --url 'https://dev.api.baanx.com/v1/delegation/token' \
  --header 'x-client-key: YOUR_PUBLIC_KEY' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "token": "100a99cf-f4d3-4fa1-9be9-2e9828b20ebc",
  "nonce": "5f8a9b2c4d3e1a7b9c6d8e2f"
}

Response Codes

Code	Description
200	Delegation token generated successfully
401	Authentication failed - invalid or expired access token
422	Validation error - invalid request parameters
498	Invalid client key
499	Missing client key
500	Internal server error

Next Steps

After receiving the delegation token:

Store the token temporarily in your application state or session
Pass it to your frontend where the user will connect their wallet
Proceed to Step 2 - implement wallet connection UI (MetaMask, WalletConnect, Phantom, etc.)
Complete Step 3 - submit delegation proof to the appropriate endpoint:
- POST /v1/delegation/evm/post-approval for EVM chains
- POST /v1/delegation/solana/post-approval for Solana

Token Characteristics

Important Token Properties:

Single-Use: The token becomes invalid after successful use in Step 3
10 Minute Expiry: Complete the entire delegation flow within this timeframe
UUID Format: Token follows standard UUID v4 format
Non-Renewable: If expired, generate a new token by calling this endpoint again

Implementation Example

Here’s a complete backend flow example:

Python Backend Flow

import requests
from typing import Dict

def initiate_delegation(user_access_token: str) -> Dict[str, str]:
    url = "https://dev.api.baanx.com/v1/delegation/token"

    headers = {
        "x-client-key": "YOUR_PUBLIC_KEY",
        "Authorization": f"Bearer {user_access_token}"
    }

    response = requests.get(url, headers=headers)

    if response.status_code == 200:
        data = response.json()
        delegation_token = data["token"]
        nonce = data["nonce"]

        # Store both token and nonce temporarily (e.g., in session, cache, or database)
        # Pass both values to your frontend for Step 2
        return {
            "success": True,
            "token": delegation_token,
            "nonce": nonce
        }
    else:
        return {
            "success": False,
            "error": response.json().get("message", "Failed to generate token")
        }

# Usage
result = initiate_delegation(user_access_token="user_token_here")
if result["success"]:
    print(f"Send these to frontend - Token: {result['token']}, Nonce: {result['nonce']}")
else:
    print(f"Error: {result['error']}")

Common Error Scenarios

Token Expiration

If the user takes longer than 10 minutes to complete the wallet connection and approval:

{
  "message": "Delegation token has expired"
}

Solution: Generate a new token by calling this endpoint again.

Invalid Access Token

If the user’s access token is invalid or expired:

{
  "message": "Invalid or expired access token"
}

Solution: Refresh the user’s access token using the OAuth refresh token flow.

Missing Authentication

If required headers are missing:

{
  "message": "Missing required header: Authorization"
}

Solution: Ensure both x-client-key and Authorization headers are included.

Best Practices

Security Considerations

Never expose tokens to client-side logging - delegation tokens should be handled securely
Use HTTPS only - all API communication must be encrypted
Implement token cleanup - clear expired tokens from your storage
Validate token format - ensure received token is a valid UUID before passing to frontend

Error Handling

Implement retry logic with exponential backoff for network failures
Handle token expiration gracefully - inform users they need to restart the flow
Provide clear user feedback - explain why delegation failed and next steps
Log errors appropriately - track failures for debugging without exposing sensitive data

User Experience

Display progress indicators - show users they’re on Step 1 of 3
Set user expectations - inform users about the ~10 minute time limit
Provide help documentation - link to guides explaining the delegation process
Enable easy restart - if token expires, make it simple to generate a new one

POST /v1/delegation/evm/post-approval - Complete EVM wallet delegation (Step 3)
POST /v1/delegation/solana/post-approval - Complete Solana wallet delegation (Step 3)
GET /v1/wallet/external - List delegated wallets
Manage External Wallet Priority - Get and update wallet priority order

Getting Started

Authentication

Consent Management

User Management

Card Operations

Wallet Management

Delegation

Overview

Delegation Workflow

Authentication

Query Parameters

Response

Response Codes

Next Steps

Token Characteristics

Implementation Example

Common Error Scenarios

Token Expiration

Invalid Access Token

Missing Authentication

Best Practices

Further Reading

Getting Started

Authentication

Consent Management

User Management

Card Operations

Wallet Management

Delegation

​Overview

​Delegation Workflow

​Authentication

​Query Parameters

​Response

​Response Codes

​Next Steps

​Token Characteristics

​Implementation Example

​Common Error Scenarios

​Token Expiration

​Invalid Access Token

​Missing Authentication

​Best Practices

​Related Endpoints

​Further Reading

Overview

Delegation Workflow

Authentication

Query Parameters

Response

Response Codes

Next Steps

Token Characteristics

Implementation Example

Common Error Scenarios

Token Expiration

Invalid Access Token

Missing Authentication

Best Practices

Related Endpoints

Further Reading