Get Delegation Token

curl --request GET \
  --url https://api.example.com/v1/delegation/token \
  --header 'Authorization: <authorization>' \
  --header 'x-client-key: <x-client-key>'

import requests

url = "https://api.example.com/v1/delegation/token"

headers = {
    "x-client-key": "<x-client-key>",
    "Authorization": "<authorization>"
}

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

print(response.text)

const options = {
  method: 'GET',
  headers: {'x-client-key': '<x-client-key>', Authorization: '<authorization>'}
};

fetch('https://api.example.com/v1/delegation/token', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/delegation/token",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "x-client-key: <x-client-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/delegation/token"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-client-key", "<x-client-key>")
	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/delegation/token")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-client-key"] = '<x-client-key>'
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

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

{
  "token": "ABC_100a99cf-f4d3-4fa1-9be9-2e9828b20ebc",
  "nonce": "5f8a9b2c4d3e1a7b9c6d8e2f",
  "faucet": {
    "success": true,
    "network": "linea",
    "status": "confirmed",
    "transactionHash": "0xabc123def456..."
  }
}

{
  "token": "ABC_100a99cf-f4d3-4fa1-9be9-2e9828b20ebc",
  "nonce": "5f8a9b2c4d3e1a7b9c6d8e2f",
  "faucet": {
    "success": true,
    "network": "linea",
    "status": "pending",
    "message": "Gas funds request submitted, transaction pending"
  }
}

GET

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

import requests

url = "https://api.example.com/v1/delegation/token"

headers = {
    "x-client-key": "<x-client-key>",
    "Authorization": "<authorization>"
}

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

print(response.text)

const options = {
  method: 'GET',
  headers: {'x-client-key': '<x-client-key>', Authorization: '<authorization>'}
};

fetch('https://api.example.com/v1/delegation/token', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/delegation/token",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "x-client-key: <x-client-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/delegation/token"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-client-key", "<x-client-key>")
	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/delegation/token")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-client-key"] = '<x-client-key>'
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

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

{
  "token": "ABC_100a99cf-f4d3-4fa1-9be9-2e9828b20ebc",
  "nonce": "5f8a9b2c4d3e1a7b9c6d8e2f",
  "faucet": {
    "success": true,
    "network": "linea",
    "status": "confirmed",
    "transactionHash": "0xabc123def456..."
  }
}

{
  "token": "ABC_100a99cf-f4d3-4fa1-9be9-2e9828b20ebc",
  "nonce": "5f8a9b2c4d3e1a7b9c6d8e2f",
  "faucet": {
    "success": true,
    "network": "linea",
    "status": "pending",
    "message": "Gas funds request submitted, transaction pending"
  }
}

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:

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-approval for EVM chains (Linea/Ethereum)
- POST /v1/delegation/solana/post-approval for Solana

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

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

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

curl -X GET "https://api.baanx.com/v1/delegation/token?faucet=true&address=0x3a11a86cf218c448be519728cd3ac5c741fb3424&network=linea" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

// Standard — no faucet
const response = await fetch('https://api.baanx.com/v1/delegation/token', {
  method: 'GET',
  headers: {
    'x-client-key': 'YOUR_CLIENT_KEY',
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  }
});

const data = await response.json();
// Store token and nonce — pass both to your frontend for Step 2
console.log('Token:', data.token);
console.log('Nonce:', data.nonce);

import requests

url = "https://api.baanx.com/v1/delegation/token"
headers = {
    "x-client-key": "YOUR_CLIENT_KEY",
    "Authorization": "Bearer YOUR_ACCESS_TOKEN"
}

# Optional: include faucet params
params = {
    "faucet": "true",
    "address": "0x3a11a86cf218c448be519728cd3ac5c741fb3424",
    "network": "linea"
}

response = requests.get(url, headers=headers, params=params)
data = response.json()

print(f"Token: {data['token']}")
print(f"Nonce: {data['nonce']}")
if "faucet" in data:
    print(f"Faucet status: {data['faucet']['status']}")

interface FaucetResult {
  success: boolean;
  network: string;
  status?: 'confirmed' | 'pending' | 'declined';
  transactionHash?: string;
  message?: string;
  error?: string;
}

interface DelegationTokenResponse {
  token: string;
  nonce: string;
  faucet?: FaucetResult;
}

const getDelegationToken = async (
  walletAddress?: string,
  network?: 'linea' | 'solana' | 'base'
): Promise<DelegationTokenResponse> => {
  const url = new URL('https://api.baanx.com/v1/delegation/token');
  if (walletAddress && network) {
    url.searchParams.set('faucet', 'true');
    url.searchParams.set('address', walletAddress);
    url.searchParams.set('network', network);
  }

  const response = await fetch(url.toString(), {
    method: 'GET',
    headers: {
      'x-client-key': 'YOUR_CLIENT_KEY',
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
    }
  });

  // 207 still returns a usable token — handle both 200 and 207
  if (!response.ok && response.status !== 207) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  return await response.json();
};

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

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

{
  "token": "ABC_100a99cf-f4d3-4fa1-9be9-2e9828b20ebc",
  "nonce": "5f8a9b2c4d3e1a7b9c6d8e2f",
  "faucet": {
    "success": true,
    "network": "linea",
    "status": "confirmed",
    "transactionHash": "0xabc123def456..."
  }
}

{
  "token": "ABC_100a99cf-f4d3-4fa1-9be9-2e9828b20ebc",
  "nonce": "5f8a9b2c4d3e1a7b9c6d8e2f",
  "faucet": {
    "success": true,
    "network": "linea",
    "status": "pending",
    "message": "Gas funds request submitted, transaction 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.

{
  "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..."
  }
}

{
  "token": "ABC_100a99cf-f4d3-4fa1-9be9-2e9828b20ebc",
  "nonce": "5f8a9b2c4d3e1a7b9c6d8e2f",
  "faucet": {
    "success": false,
    "network": "base",
    "status": "declined",
    "error": "Gas funds request was declined"
  }
}

{
  "token": "ABC_100a99cf-f4d3-4fa1-9be9-2e9828b20ebc",
  "nonce": "5f8a9b2c4d3e1a7b9c6d8e2f",
  "faucet": {
    "success": false,
    "network": "linea",
    "error": "Gas funds service error"
  }
}

Error Responses

{
  "message": "Not authenticated"
}

{
  "message": "Not authorized"
}

{
  "message": "Internal server error"
}

Next Steps

After receiving the delegation token:

Store both token and nonce temporarily 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

GET /v1/delegation/chain/config — Get contract addresses and chain IDs needed for Step 2
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 registered external wallets

Overview

Authentication

User

Card

Orders

Wallet

Delegation

Consent

Referral

Webhooks

Get Delegation Token

Overview

Gas Faucet (Optional)

Authentication

Request

Headers

Query Parameters

Request Examples

Response

200 — Success

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

Error Responses

Next Steps

​Overview

​Gas Faucet (Optional)

​Authentication

​Request

​Headers

​Query Parameters

​Request Examples

​Response

​200 — Success

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

​Error Responses

​Next Steps

​Related Endpoints

Overview

Gas Faucet (Optional)

Authentication

Request

Headers

Query Parameters

Request Examples

Response

200 — Success

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

Error Responses

Next Steps

Related Endpoints