> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baanx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Delegation Token

> Retrieve a single-use delegation token to initiate wallet delegation, with optional gas faucet

GET [https://api.baanx.com/v1/delegation/token](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:
   * [`POST /v1/delegation/evm/post-approval`](/api-reference/delegation/evm-post-approval) for EVM chains (Linea/Ethereum)
   * [`POST /v1/delegation/solana/post-approval`](/api-reference/delegation/solana-post-approval) for Solana

See the [Delegation Implementation Guide](/guides/delegation/implementation) for complete integration details.

<Warning>
  **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
</Warning>

## 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.

<Note>
  **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.
</Note>

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

```bash theme={null} theme={null}
x-client-key: YOUR_CLIENT_KEY
Authorization: Bearer YOUR_ACCESS_TOKEN
```

## Request

### Headers

<ParamField header="x-client-key" type="string" required>
  Your public API client key
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer token for the authenticated user
</ParamField>

<ParamField header="x-us-env" type="boolean" default={false}>
  Set to `true` to route requests to the US backend environment (Linea US routing)
</ParamField>

### Query Parameters

<ParamField query="faucet" type="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`.
</ParamField>

<ParamField query="address" type="string">
  The user's wallet address — EVM format (`0x` + 40 hex chars) or Solana base58 public key. Required when `faucet=true`.

  **Example:** `0x3a11a86cf218c448be519728cd3ac5c741fb3424`
</ParamField>

<ParamField query="network" type="string">
  The blockchain network for the gas faucet. Required when `faucet=true`.

  **Accepted values:** `linea`, `solana`, `base`
</ParamField>

### Request Examples

<CodeGroup>
  ```bash cURL - Standard theme={null} theme={null}
  curl -X GET https://api.baanx.com/v1/delegation/token \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```

  ```bash cURL - With Faucet theme={null} theme={null}
  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"
  ```

  ```javascript JavaScript theme={null} theme={null}
  // 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);
  ```

  ```python Python theme={null} theme={null}
  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']}")
  ```

  ```typescript TypeScript theme={null} theme={null}
  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();
  };
  ```
</CodeGroup>

## Response

### 200 — Success

Returned when no faucet was requested, or when the faucet request succeeded.

<ResponseField name="token" type="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`
</ResponseField>

<ResponseField name="nonce" type="string" required>
  Unique nonce generated by Applied Blockchain. Must be included in the Step 3 post-approval request alongside the token.

  **Example:** `5f8a9b2c4d3e1a7b9c6d8e2f`
</ResponseField>

<ResponseField name="faucet" type="object">
  Only present if `faucet=true` was requested. Contains the result of the gas faucet request.
</ResponseField>

<ResponseField name="faucet.success" type="boolean">
  Whether the faucet request was processed successfully
</ResponseField>

<ResponseField name="faucet.network" type="string">
  The blockchain network the gas was sent on
</ResponseField>

<ResponseField name="faucet.status" type="string">
  Transaction status: `confirmed`, `pending`, or `declined`
</ResponseField>

<ResponseField name="faucet.transactionHash" type="string">
  On-chain transaction hash — only present when `status` is `confirmed`
</ResponseField>

<ResponseField name="faucet.message" type="string">
  Informational message — present when `status` is `pending`
</ResponseField>

<ResponseExample>
  ```json 200 - Standard (no faucet) theme={null} theme={null}
  {
    "token": "ABC_100a99cf-f4d3-4fa1-9be9-2e9828b20ebc",
    "nonce": "5f8a9b2c4d3e1a7b9c6d8e2f"
  }
  ```

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

  ```json 200 - Faucet pending theme={null} theme={null}
  {
    "token": "ABC_100a99cf-f4d3-4fa1-9be9-2e9828b20ebc",
    "nonce": "5f8a9b2c4d3e1a7b9c6d8e2f",
    "faucet": {
      "success": true,
      "network": "linea",
      "status": "pending",
      "message": "Gas funds request submitted, transaction pending"
    }
  }
  ```
</ResponseExample>

### 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.

<ResponseExample>
  ```json 207 - Already received faucet theme={null} theme={null}
  {
    "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..."
    }
  }
  ```

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

  ```json 207 - Faucet service error theme={null} theme={null}
  {
    "token": "ABC_100a99cf-f4d3-4fa1-9be9-2e9828b20ebc",
    "nonce": "5f8a9b2c4d3e1a7b9c6d8e2f",
    "faucet": {
      "success": false,
      "network": "linea",
      "error": "Gas funds service error"
    }
  }
  ```
</ResponseExample>

## Error Responses

<ResponseExample>
  ```json 401 - Unauthorized theme={null} theme={null}
  {
    "message": "Not authenticated"
  }
  ```

  ```json 403 - Forbidden theme={null} theme={null}
  {
    "message": "Not authorized"
  }
  ```

  ```json 500 - Internal Server Error theme={null} theme={null}
  {
    "message": "Internal server error"
  }
  ```
</ResponseExample>

## 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:
   * [POST /v1/delegation/evm/post-approval](/api-reference/delegation/evm-post-approval) — EVM chains (Linea/Ethereum)
   * [POST /v1/delegation/solana/post-approval](/api-reference/delegation/solana-post-approval) — Solana

## Related Endpoints

* [`GET /v1/delegation/chain/config`](/api-reference/delegation/chain-config) — Get contract addresses and chain IDs needed for Step 2
* [`POST /v1/delegation/evm/post-approval`](/api-reference/delegation/evm-post-approval) — Complete EVM wallet delegation (Step 3)
* [`POST /v1/delegation/solana/post-approval`](/api-reference/delegation/solana-post-approval) — Complete Solana wallet delegation (Step 3)
* [`GET /v1/wallet/external`](/api-reference/wallet/external) — List registered external wallets