Get Delegation Token
Delegation
Get Delegation Token
Retrieve a single-use delegation token to initiate wallet delegation, with optional gas faucet
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.
Faucet behaviour:
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:- Backend (this endpoint) — Request delegation token
- Frontend (your implementation) — User connects wallet and approves blockchain transaction
- Backend — Submit delegation proof:
POST /v1/delegation/evm/post-approvalfor EVM chains (Linea/Ethereum)POST /v1/delegation/solana/post-approvalfor Solana
Gas Faucet (Optional)
Setfaucet=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.
- 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, ordeclined - 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
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: 0x3a11a86cf218c448be519728cd3ac5c741fb3424string
The blockchain network for the gas faucet. Required when
faucet=true.Accepted values: linea, solana, baseRequest 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-2e9828b20ebcstring
required
Unique nonce generated by Applied Blockchain. Must be included in the Step 3 post-approval request alongside the token.Example:
5f8a9b2c4d3e1a7b9c6d8e2fobject
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 declinedstring
On-chain transaction hash — only present when
status is confirmedstring
Informational message — present when
status is pending207 — Multi-Status (Faucet Failed, Token Issued)
Returned whenfaucet=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:- Store both
tokenandnoncetemporarily in your application state or session - Pass them 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 the delegation proof:
- POST /v1/delegation/evm/post-approval — EVM chains (Linea/Ethereum)
- POST /v1/delegation/solana/post-approval — Solana
Related Endpoints
GET /v1/delegation/chain/config— Get contract addresses and chain IDs needed for Step 2POST /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 registered external wallets