GET /whitelist/investor-tokens endpoint documentation

gistfile0.txt

# GET /whitelist/investor-tokens

Returns all tokens a wallet is whitelisted for in the active merkle root, including merkle proofs, token decimals, oracle prices, and USD values.

## Query Parameters

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `wallet`  | Yes      | —       | Wallet address (hex, e.g. `0xabc...`) |
| `chainId` | No       | Config default | Chain ID (e.g. `146` for Sonic, `1` for Ethereum) |

## Response

```json
{
  "wallet": "0xAbC1234567890abcDEF1234567890aBcDeF12345",
  "tokens": [
    "0x29219dd400f2Bf60E5a23d13Be72B486D4038894",
    "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"
  ],
  "tokenInfos": [
    {
      "token": "0x29219dd400f2Bf60E5a23d13Be72B486D4038894",
      "proof": ["0xabc...", "0xdef..."],
      "proofAmount": "1000000000",
      "proofAmountFormatted": "1000.00",
      "proofAmountUsd": "1000.00",
      "decimals": 6,
      "oraclePrice": "100000000",
      "oraclePriceFormatted": "1.0000",
      "oraclePriceDecimals": 8
    },
    {
      "token": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
      "proof": ["0x123...", "0x456..."],
      "proofAmount": "500000000000000000",
      "proofAmountFormatted": "0.5000",
      "proofAmountUsd": "1250.00",
      "decimals": 18,
      "oraclePrice": "250000000000",
      "oraclePriceFormatted": "2500.00",
      "oraclePriceDecimals": 8
    }
  ],
  "merkleRoot": "0x1234abcd...",
  "chainId": 146,
  "found": true
}
```

## Field Reference

### Top-level

| Field        | Type     | Description |
|--------------|----------|-------------|
| `wallet`     | string   | Checksummed wallet address |
| `tokens`     | string[] | List of token addresses the wallet is whitelisted for |
| `tokenInfos` | array    | Detailed info per token (see below) |
| `merkleRoot` | string   | Current active merkle root |
| `chainId`    | number   | Chain ID |
| `found`      | boolean  | `true` if wallet has any whitelisted tokens |

### `tokenInfos[]`

| Field                  | Type     | Description |
|------------------------|----------|-------------|
| `token`                | string   | Token contract address |
| `proof`                | string[] | Merkle proof hashes (pass to contract) |
| `proofAmount`          | string   | Raw amount in wei (pass to contract) |
| `proofAmountFormatted` | string   | Human-readable decimalized amount (e.g. `"1000.00"`) |
| `proofAmountUsd`       | string   | **USD value of the proof amount** — `(proofAmount / 10^decimals) * (oraclePrice / 10^oraclePriceDecimals)`. This is the final display value for the frontend. |
| `decimals`             | number   | Token decimals (e.g. `6` for USDC, `18` for WETH) |
| `oraclePrice`          | string   | Raw oracle price (Aave oracle, 1e8 scale) |
| `oraclePriceFormatted` | string   | Decimalized oracle price (e.g. `"1.0012"`, `"2500.00"`) |
| `oraclePriceDecimals`  | number   | Oracle price decimals (typically `8`) |

## Notes

- `proofAmountUsd` is the key field for displaying allocation value to the user
- `proof` and `proofAmount` are the raw values to pass to the smart contract for on-chain verification
- Oracle price fields are omitted if the pricing service is unavailable
- Formatting: values >= 1000 use 2 decimal places, values < 1000 use 4 decimal places
- Token decimals fall back to 18 if not resolvable

## Example Usage (TypeScript)

```typescript
const res = await fetch(`/whitelist/investor-tokens?wallet=${address}&chainId=146`);
const data = await res.json();

if (data.found) {
  for (const token of data.tokenInfos) {
    console.log(`${token.token}: ${token.proofAmountFormatted} tokens ($${token.proofAmountUsd})`);
    // For contract call:
    // contract.invest(token.proof, token.proofAmount, token.token)
  }
}
```