# Index Token

### Endpoint

```
POST https://clanker.world/api/tokens/index
```

### Authentication

Requires a valid partner API key passed in the `x-api-key` header. API keys are validated against the `partners` table in the database.

### Rate Limiting

* **10 requests per minute** per IP address
* Returns `429 Too Many Requests` when limit is exceeded

### Request

#### Headers

| Header         | Required | Description                        |
| -------------- | -------- | ---------------------------------- |
| `Content-Type` | Yes      | Must be `application/json`         |
| `x-api-key`    | Yes      | Partner API key for authentication |

#### Body

| Field     | Type     | Required | Description                                                               |
| --------- | -------- | -------- | ------------------------------------------------------------------------- |
| `txHash`  | `string` | Yes      | Transaction hash of the token deployment (0x-prefixed, 64 hex characters) |
| `chainId` | `number` | Yes      | Chain ID where the token was deployed                                     |

#### Supported Chain IDs

| Chain    | Chain ID |
| -------- | -------- |
| Base     | `8453`   |
| Monad    | `143`    |
| Arbitrum | `42161`  |
| Unichain | `130`    |
| Ethereum | `1`      |

### Response

#### Success (200)

```json
{
  "success": true,
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "url": "/clanker/0x1234567890abcdef1234567890abcdef12345678"
}
```

#### Error Responses

| Status | Error                             | Description                          |
| ------ | --------------------------------- | ------------------------------------ |
| `400`  | `Invalid transaction hash format` | txHash is missing or not a valid hex |
| `400`  | `Unsupported chain`               | chainId is missing or not supported  |
| `400`  | `Failed to index transaction`     | Indexer could not process the tx     |
| `401`  | `API key is required`             | Missing x-api-key header             |
| `401`  | `Unauthorized`                    | Invalid API key                      |
| `429`  | `Too many requests...`            | Rate limit exceeded                  |
| `500`  | `Internal server error`           | Unexpected server error              |

### Example

#### cURL

```bash
curl -X POST https://clanker.world/api/tokens/index \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "chainId": 143
  }'
```

#### JavaScript (fetch)

```javascript
const response = await fetch('https://clanker.world/api/tokens/index', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY',
  },
  body: JSON.stringify({
    txHash: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
    chainId: 143,
  }),
});

const data = await response.json();
console.log(data);
// { success: true, address: "0x...", url: "/clanker/0x..." }
```

### Notes

* The endpoint indexes the token synchronously and returns the token address on success
* Ensure the token deployment transaction has been confirmed prior to fetching the indexing
* If the token has already been indexed, it will update the existing record
* After successful indexing, the token will be available at the returned URL