Skip to main content
GET
/
v1
/
delegation
/
token
Get Delegation Token
curl --request GET \
  --url https://api.example.com/v1/delegation/token \
  --header 'Authorization: <authorization>' \
  --header 'x-client-key: <x-client-key>'
{
  "token": "ABC_100a99cf-f4d3-4fa1-9be9-2e9828b20ebc",
  "nonce": "5f8a9b2c4d3e1a7b9c6d8e2f"
}
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: 
x-client-key: YOUR_CLIENT_KEY
Authorization: Bearer YOUR_ACCESS_TOKEN

​
Request

​
Headers

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

​
Query Parameters

​
faucet
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.
​
address
string
The user’s wallet address — EVM format (0x + 40 hex chars) or Solana base58 public key. Required when faucet=true.Example: 0x3a11a86cf218c448be519728cd3ac5c741fb3424
​
network
string
The blockchain network for the gas faucet. Required when faucet=true.Accepted values: linea, solana, base

​
Request Examples

curl -X GET https://api.baanx.com/v1/delegation/token \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Response

​
200 — Success

Returned when no faucet was requested, or when the faucet request succeeded.
​
token
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
​
nonce
string
required
Unique nonce generated by Applied Blockchain. Must be included in the Step 3 post-approval request alongside the token.Example: 5f8a9b2c4d3e1a7b9c6d8e2f
​
faucet
object
Only present if faucet=true was requested. Contains the result of the gas faucet request.
​
faucet.success
boolean
Whether the faucet request was processed successfully
​
faucet.network
string
The blockchain network the gas was sent on
​
faucet.status
string
Transaction status: confirmed, pending, or declined
​
faucet.transactionHash
string
On-chain transaction hash — only present when status is confirmed
​
faucet.message
string
Informational message — present when status is pending
{
  "token": "ABC_100a99cf-f4d3-4fa1-9be9-2e9828b20ebc",
  "nonce": "5f8a9b2c4d3e1a7b9c6d8e2f"
}

​
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. 
{
  "token": "ABC_100a99cf-f4d3-4fa1-9be9-2e9828b20ebc",
  "nonce": "5f8a9b2c4d3e1a7b9c6d8e2f",
  "faucet": {
    "success": false,
    "network": "linea",
    "status": "confirmed",
    "error": "User has already received gas funds",
    "transactionHash": "0xprevious-tx-hash..."
  }
}

​
Error Responses

{
  "message": "Not authenticated"
}

​
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: