> For the complete documentation index, see [llms.txt](https://docs.astralbeam.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.astralbeam.io/api-reference/tokens.md).

# Tokens

Endpoints for querying supported tokens and their addresses across chains, including real-time liquidity data.

## List All Tokens

Get all registered tokens with their addresses on each supported EVM chain and available liquidity.

```
GET /api/v1/tokens
```

### Query Parameters

| Name               | Type    | Default | Description                                  |
| ------------------ | ------- | ------- | -------------------------------------------- |
| `includeLiquidity` | boolean | `true`  | Include real-time liquidity data in response |

### Response

```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "symbol": "USDC",
      "name": "USD Coin",
      "decimalsEth": 6,
      "decimalsCasper": 6,
      "originChain": "evm",
      "casperHash": "62d62d5cb43d095b9096ecfe3a3f2bd4d2a1df4020cd9cda94594edb77fedf38",
      "isActive": true,
      "addresses": {
        "sepolia": "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
        "base-sepolia": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
        "polygon-amoy": "0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582"
      },
      "evmLiquidity": {
        "sepolia": "5000.00",
        "base-sepolia": "0.00",
        "polygon-amoy": "1200.50"
      },
      "casperLiquidity": null,
      "createdAt": "2024-01-15T10:00:00Z",
      "updatedAt": "2024-01-15T10:00:00Z"
    },
    {
      "id": 2,
      "symbol": "wCSPR",
      "name": "Wrapped CSPR",
      "decimalsEth": 9,
      "decimalsCasper": 9,
      "originChain": "casper",
      "casperHash": "3d80df21ba4ee4d66a2a1f60c32570dd5685e4b279f6538162a5fd1314847c1e",
      "isActive": true,
      "addresses": {
        "sepolia": "0x36A3179A09C3b3DFf9FC3d81704e0c727537f197",
        "base-sepolia": "0x36A3179A09C3b3DFf9FC3d81704e0c727537f197"
      },
      "evmLiquidity": null,
      "casperLiquidity": "10000.00"
    }
  ]
}
```

### Example

```bash
# With liquidity data (default)
curl "https://api.csprbridge.com/api/v1/tokens"

# Without liquidity data (faster)
curl "https://api.csprbridge.com/api/v1/tokens?includeLiquidity=false"
```

***

## Get Token by ID

Get a specific token by its database ID.

```
GET /api/v1/tokens/{id}
```

### Parameters

| Name               | In    | Type    | Required | Description                            |
| ------------------ | ----- | ------- | -------- | -------------------------------------- |
| `id`               | path  | integer | yes      | Token database ID                      |
| `includeLiquidity` | query | boolean | no       | Include liquidity data (default: true) |

### Response

```json
{
  "success": true,
  "data": {
    "id": 1,
    "symbol": "USDC",
    "name": "USD Coin",
    "decimalsEth": 6,
    "decimalsCasper": 6,
    "originChain": "evm",
    "casperHash": "62d62d5cb43d095b9096ecfe3a3f2bd4d2a1df4020cd9cda94594edb77fedf38",
    "isActive": true,
    "addresses": {
      "sepolia": "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
      "base-sepolia": "0x036CbD53842c5426634e7929541eC2318f3dCF7e"
    },
    "evmLiquidity": {
      "sepolia": "5000.00",
      "base-sepolia": "0.00"
    },
    "casperLiquidity": null
  }
}
```

### Errors

| Code | Description     |
| ---- | --------------- |
| 404  | Token not found |

### Example

```bash
curl "https://api.csprbridge.com/api/v1/tokens/1"
```

***

## Get Token by EVM Address

Find a token by its address on any EVM chain.

```
GET /api/v1/tokens/address/{address}
```

### Parameters

| Name               | In    | Type    | Required | Description                            |
| ------------------ | ----- | ------- | -------- | -------------------------------------- |
| `address`          | path  | string  | yes      | EVM token address (0x...)              |
| `includeLiquidity` | query | boolean | no       | Include liquidity data (default: true) |

### Response

Returns the same format as "Get Token by ID".

### Example

```bash
curl "https://api.csprbridge.com/api/v1/tokens/address/0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238"
```

### Notes

* Address matching is case-insensitive
* Works with any chain's address for the token
* Returns 404 if address not found in any chain

***

## Get Token by Ethereum Address (Legacy)

Legacy alias for address lookup — searches all EVM chains. Prefer `/tokens/address/{address}` for new integrations.

```
GET /api/v1/tokens/ethereum/{address}
```

### Parameters

| Name      | In   | Type   | Required | Description                             |
| --------- | ---- | ------ | -------- | --------------------------------------- |
| `address` | path | string | yes      | EVM token address (`0x` + 40 hex chars) |

Returns the same format as "Get Token by Address". Invalid address format returns 400.

***

## Get Token by Casper Hash

Find a token by its CEP-18 contract hash on Casper.

```
GET /api/v1/tokens/casper/{hash}
```

### Parameters

| Name               | In    | Type    | Required | Description                            |
| ------------------ | ----- | ------- | -------- | -------------------------------------- |
| `hash`             | path  | string  | yes      | Casper contract hash                   |
| `includeLiquidity` | query | boolean | no       | Include liquidity data (default: true) |

### Response

Returns the same format as "Get Token by ID".

### Example

```bash
curl "https://api.csprbridge.com/api/v1/tokens/casper/62d62d5cb43d095b9096ecfe3a3f2bd4d2a1df4020cd9cda94594edb77fedf38"
```

***

## Get Tokens by Chain

Get all tokens available on a specific EVM chain.

```
GET /api/v1/tokens/chain/{chainName}
```

### Parameters

| Name               | In    | Type    | Required | Description                            |
| ------------------ | ----- | ------- | -------- | -------------------------------------- |
| `chainName`        | path  | string  | yes      | Chain short name                       |
| `includeLiquidity` | query | boolean | no       | Include liquidity data (default: true) |

### Valid Chain Names

* `sepolia` - Ethereum Sepolia
* `base-sepolia` - Base Sepolia
* `arbitrum-sepolia` - Arbitrum Sepolia
* `polygon-amoy` - Polygon Amoy
* `robinhood` - Robinhood Chain (`4663`), currently disabled with no locker or token mappings
* `robinhood-testnet` - Robinhood Chain Testnet (`46630`), locker, TEST mapping, and round trip verified

A chain's presence in the chain registry does not imply token availability. Robinhood mainnet has no token mapping. Robinhood testnet TEST is registered as `0xc65db6eE6f16919332275B23D80C71A0dd478EF6` against Casper CEP-18 `d909d1b93b97860b6030747e82a60ff15b1afc8005f43661e526fa654546b685`; the active testnet route has bidirectional finalized-mode E2E certification.

### Response

```json
{
  "success": true,
  "chain": "sepolia",
  "data": [
    {
      "id": 1,
      "symbol": "USDC",
      "name": "USD Coin",
      "decimalsEth": 6,
      "addresses": {
        "sepolia": "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238"
      },
      "evmLiquidity": {
        "sepolia": "5000.00"
      },
      "casperLiquidity": null
    }
  ]
}
```

### Example

```bash
curl "https://api.csprbridge.com/api/v1/tokens/chain/sepolia"
```

***

## List Supported Chains (Token-Scoped)

Convenience alias under the tokens router returning supported EVM chains. Equivalent to [`GET /api/v1/chains`](/api-reference/chains.md).

```
GET /api/v1/tokens/chains
```

### Parameters

| Name      | In    | Type    | Required | Description                              |
| --------- | ----- | ------- | -------- | ---------------------------------------- |
| `enabled` | query | boolean | no       | Filter by enabled status (default: true) |

Returns the same format as the [Chains API](/api-reference/chains.md).

***

## Token Schema

### Token Object

| Field             | Type         | Description                                                                                           |
| ----------------- | ------------ | ----------------------------------------------------------------------------------------------------- |
| `id`              | integer      | Unique database ID                                                                                    |
| `symbol`          | string       | Token symbol (e.g., "USDC")                                                                           |
| `name`            | string       | Full token name                                                                                       |
| `decimalsEth`     | integer      | Decimals on EVM chains                                                                                |
| `decimalsCasper`  | integer      | Decimals on Casper                                                                                    |
| `originChain`     | string       | Original chain ("evm" or "casper")                                                                    |
| `casperHash`      | string       | CEP-18 contract hash on Casper (64-char hex)                                                          |
| `wrappedAddress`  | string       | Wrapped token address (if applicable)                                                                 |
| `isActive`        | boolean      | Whether token is actively supported                                                                   |
| `addresses`       | object       | Map of chainName → address                                                                            |
| `evmLiquidity`    | object\|null | Map of chainName → available liquidity on that chain (EVM-native tokens only, null for Casper-native) |
| `casperLiquidity` | string\|null | Available liquidity on Casper (Casper-native tokens only, null for EVM-native)                        |
| `createdAt`       | datetime     | When token was registered                                                                             |
| `updatedAt`       | datetime     | Last update time                                                                                      |

### Addresses Object

The `addresses` field contains token addresses for each supported chain:

```json
{
  "addresses": {
    "sepolia": "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
    "base-sepolia": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
    "polygon-amoy": "0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582"
  }
}
```

* Keys are chain short names
* Values are token contract addresses (checksummed)
* Null/missing key means token not available on that chain

### Liquidity Fields

The API provides real-time liquidity data to help frontends prevent failed bridge transactions:

#### `evmLiquidity`

Available liquidity on each EVM chain for **Casper → EVM** bridge direction.

**For EVM-native tokens** (e.g., USDC, WETH):

```json
{
  "evmLiquidity": {
    "sepolia": "5000.00",
    "base-sepolia": "0.00",
    "polygon-amoy": "1200.50"
  }
}
```

**For Casper-native tokens** (e.g., wCSPR, sCSPR):

```json
{
  "evmLiquidity": null
}
```

* Shows how much can be **unlocked** on each EVM chain
* Per-chain constraint: each chain has independent locked amounts
* Use this to validate burn amounts before initiating Casper → EVM transfers
* Returns `null` for Casper-native tokens (wrapped ERC-20s are minted/burned on demand, not held in locker)

#### `casperLiquidity`

Available liquidity on Casper for **EVM → Casper** bridge direction (native Casper tokens only):

```json
{
  "casperLiquidity": "10000.00"
}
```

* Only present for tokens with `originChain: "casper"` (e.g., wCSPR, sCSPR)
* Shows how much can be **unlocked** on Casper
* Global constraint: this pool is shared across all EVM chains
* Use this to validate burn amounts before initiating EVM → Casper wrapped token transfers
* Returns `null` for EVM-origin tokens (they mint on Casper, no unlock constraint)

### Liquidity Constraints by Direction

| Bridge Direction | Token Type              | Liquidity Field       | Constraint                              |
| ---------------- | ----------------------- | --------------------- | --------------------------------------- |
| EVM → Casper     | EVM-origin (USDC, WETH) | N/A                   | None (mints new CEP-18)                 |
| Casper → EVM     | EVM-origin (USDC, WETH) | `evmLiquidity[chain]` | Per-chain (unlock from specific locker) |
| Casper → EVM     | Casper-native (wCSPR)   | N/A                   | None (mints new wrapped ERC-20)         |
| EVM → Casper     | Casper-native (wCSPR)   | `casperLiquidity`     | Global (unlock from TokenFactory)       |

***

## Usage Examples

### JavaScript - Check Liquidity Before Bridge

```javascript
// Get token with liquidity
const response = await fetch('https://api.csprbridge.com/api/v1/tokens/1');
const { data: token } = await response.json();

// For Casper → EVM bridge (unlocking ERC-20 on target chain)
// Only relevant for EVM-native tokens (evmLiquidity is null for Casper-native)
if (token.evmLiquidity !== null) {
  const targetChain = 'sepolia';
  const burnAmount = 1000;
  const availableLiquidity = parseFloat(token.evmLiquidity[targetChain] || '0');

  if (burnAmount > availableLiquidity) {
    console.error(`Insufficient liquidity on ${targetChain}. Available: ${availableLiquidity}`);
  } else {
    console.log('Liquidity check passed, proceed with bridge');
  }
}

// For EVM → Casper bridge (returning wrapped tokens to Casper)
// Only relevant for Casper-native tokens (casperLiquidity is null for EVM-native)
if (token.casperLiquidity !== null) {
  const casperAvailable = parseFloat(token.casperLiquidity);
  const burnAmount = 1000;
  if (burnAmount > casperAvailable) {
    console.error(`Insufficient Casper liquidity. Available: ${casperAvailable}`);
  }
}
```

### Python - Display Token Liquidity

```python
import requests

# Get tokens for Base Sepolia with liquidity
response = requests.get(
    'https://api.csprbridge.com/api/v1/tokens/chain/base-sepolia'
)
tokens = response.json()['data']

for token in tokens:
    symbol = token['symbol']
    address = token['addresses'].get('base-sepolia', 'N/A')

    # evmLiquidity is null for Casper-native tokens
    if token['evmLiquidity'] is not None:
        liquidity = token['evmLiquidity'].get('base-sepolia', '0.00')
        print(f"{symbol}: {address} (EVM Available: {liquidity})")
    elif token['casperLiquidity'] is not None:
        print(f"{symbol}: {address} (Casper Available: {token['casperLiquidity']})")
```

### curl with jq - Check USDC Liquidity Across Chains

```bash
# Get USDC liquidity on all chains
curl -s "https://api.csprbridge.com/api/v1/tokens" | \
  jq '.data[] | select(.symbol == "USDC") | {symbol, evmLiquidity}'

# Output:
# {
#   "symbol": "USDC",
#   "evmLiquidity": {
#     "sepolia": "5000.00",
#     "base-sepolia": "0.00",
#     "polygon-amoy": "1200.50"
#   }
# }
```

### React Hook Example

```typescript
import { useState, useEffect } from 'react';

interface Token {
  symbol: string;
  addresses: Record<string, string>;
  evmLiquidity: Record<string, string> | null;  // null for Casper-native tokens
  casperLiquidity: string | null;                // null for EVM-native tokens
  originChain: 'evm' | 'casper';
}

export function useTokenLiquidity(tokenId: number) {
  const [token, setToken] = useState<Token | null>(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    fetch(`https://api.csprbridge.com/api/v1/tokens/${tokenId}`)
      .then(res => res.json())
      .then(data => {
        setToken(data.data);
        setLoading(false);
      });
  }, [tokenId]);

  const checkLiquidity = (amount: number, targetChain: string, direction: 'toEvm' | 'toCasper') => {
    if (!token) return { valid: false, available: 0, hasConstraint: false };

    if (direction === 'toEvm') {
      // Casper → EVM: only EVM-native tokens have liquidity constraints
      if (token.evmLiquidity === null) {
        return { valid: true, available: Infinity, hasConstraint: false };
      }
      const available = parseFloat(token.evmLiquidity[targetChain] || '0');
      return { valid: amount <= available, available, hasConstraint: true };
    } else {
      // EVM → Casper: only Casper-native tokens have liquidity constraints
      if (token.casperLiquidity === null) {
        return { valid: true, available: Infinity, hasConstraint: false };
      }
      const available = parseFloat(token.casperLiquidity);
      return { valid: amount <= available, available, hasConstraint: true };
    }
  };

  return { token, loading, checkLiquidity };
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.astralbeam.io/api-reference/tokens.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.