Skip to main content
GET
Get Delegation Token
GET https://api.baanx.com/v1/delegation/token Retrieve a single-use token required to initiate wallet delegation. Optionally request gas funds for users who don’t have native tokens to pay for the delegation transaction.

Overview

This is Step 1 of the 3-step delegation flow. The returned token is required to finalise delegation in Step 3 after the user completes wallet connection and blockchain approval on the frontend. The complete delegation process:
  1. Backend (this endpoint) — Request delegation token
  2. Frontend (your implementation) — User connects wallet and approves blockchain transaction
  3. Backend — Submit delegation proof:
See the Delegation Implementation Guide for complete integration details.
Token properties:
  • Single-use only — the token becomes invalid after use in Step 3
  • ~10 minute lifetime — complete the full delegation flow before expiration
  • If the token expires, call this endpoint again to generate a new one

Gas Faucet (Optional)

Set faucet=true to request a small amount of native tokens (ETH or SOL) for users who don’t yet have funds to pay for gas fees. This enables users with empty wallets to complete the delegation flow.
One-time only per user, across all networks. If a user has already received gas funds on any network, subsequent faucet requests will fail with a 207 response — but the delegation token is still issued and the flow can proceed.
Faucet behaviour:
  • Checks whether the user is eligible (has not already received gas funds on any network)
  • If eligible: sends a small amount of native tokens and polls for confirmation (up to 10 seconds)
  • Returns one of three statuses: confirmed, pending, or declined
  • A faucet failure does not block token generation — the token is always returned
  • Returns HTTP 200 if the faucet succeeds (or was not requested), HTTP 207 if the faucet fails
Supported networks for faucet: linea, solana, base

Authentication

This endpoint requires both a client key and a Bearer token:

Request

Headers

string
required
Your public API client key
string
required
Bearer token for the authenticated user
boolean
default:false
Set to true to route requests to the US backend environment (Linea US routing)

Query Parameters

boolean
default:false
Request a small amount of native tokens (ETH/SOL) for users who don’t have funds to pay for delegation gas fees. When true, address and network are required. Supported networks: linea, solana, base.
string
The user’s wallet address — EVM format (0x + 40 hex chars) or Solana base58 public key. Required when faucet=true.Example: 0x3a11a86cf218c448be519728cd3ac5c741fb3424
string
The blockchain network for the gas faucet. Required when faucet=true.Accepted values: linea, solana, base

Request Examples

Response

200 — Success

Returned when no faucet was requested, or when the faucet request succeeded.
string
required
Single-use delegation token valid for ~10 minutes. Pass this to your frontend and include it in the Step 3 post-approval request.Example: ABC_100a99cf-f4d3-4fa1-9be9-2e9828b20ebc
string
required
Unique nonce generated by Applied Blockchain. Must be included in the Step 3 post-approval request alongside the token.Example: 5f8a9b2c4d3e1a7b9c6d8e2f
object
Only present if faucet=true was requested. Contains the result of the gas faucet request.
boolean
Whether the faucet request was processed successfully
string
The blockchain network the gas was sent on
string
Transaction status: confirmed, pending, or declined
string
On-chain transaction hash — only present when status is confirmed
string
Informational message — present when status is pending

207 — Multi-Status (Faucet Failed, Token Issued)

Returned when faucet=true was requested but the faucet could not be fulfilled. The delegation token is still valid and the flow can proceed. Treat the faucet failure as informational.

Error Responses

Next Steps

After receiving the delegation token:
  1. Store both token and nonce temporarily in your application state or session
  2. Pass them 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 the delegation proof: