Skip to main content
GET
/
v1
/
delegation
/
token
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"
}

​
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:
  1. Backend (This Endpoint): Request delegation token from API
  2. Frontend (Your Implementation): User connects wallet and approves blockchain transaction
  3. 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

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

​
Next Steps

After receiving the delegation token:
  1. Store the token temporarily in your application state or session
  2. Pass it to your frontend where the user will connect their wallet
  3. Proceed to Step 2 - implement wallet connection UI (MetaMask, WalletConnect, Phantom, etc.)
  4. Complete Step 3 - submit delegation proof to the appropriate endpoint:

​
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

  • 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
  • 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
  • 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

​
Further Reading