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

# Read and Index

> Use InkyPump's read API without confusing indexed state with transaction success.

InkyPump's read API is an indexed view of on-chain launches. Use the chain receipt as the source of truth for a write, then use the API for discovery, metrics, valuation evidence, and UI data.

## Server-to-server boundary

Call `https://inkypump.com/api/...` from your backend. The current read endpoints do not promise `Access-Control-Allow-Origin` for third-party browser origins.

Your frontend should call your own backend. Do not proxy private wallet data, private keys, or signed transactions through InkyPump.

## Always choose a chain

Send `chainId=57073` for Ink or `chainId=4663` for Robinhood on every request.

```bash theme={null}
curl "https://inkypump.com/api/token?chainId=57073&address=0x..."
```

If an endpoint returns `X-InkyPump-Chain-Id`, confirm it matches the requested chain.

## Core endpoints

| Method and path                                                        | Response envelope                                 |                                 Current limit |
| ---------------------------------------------------------------------- | ------------------------------------------------- | --------------------------------------------: |
| `GET /api/capabilities?chainId=`                                       | Deployment registry and feature flags             |                          Dynamic control read |
| `GET /api/health/ready`                                                | Service readiness details                         |                                   Health read |
| `GET /api/token?chainId=&address=`                                     | Token object                                      |                                30/min per key |
| `GET /api/tokens/recent-v2?chainId=&limit=&offset=`                    | `{ chainId, tokens, nextOffset }`                 |                                60/min per key |
| `GET /api/tokens?chainId=&page=&sortBy=`                               | `{ chainId, tokens, totalCount, totalPages }`     | 30/min; some live first-page views allow more |
| `GET /api/tokens/by-owner?chainId=&owner=`                             | `{ chainId, tokens, totalCount }`                 |                                20/min per key |
| `GET /api/tokens/batch?chainId=&addresses=a,b`                         | `{ chainId, tokens: { [address]: tokenOrNull } }` |                                30/min per key |
| `GET /api/xstocks/quote-assets?chainId=57073`                          | Release records and per-asset launch data         |                               120/min per key |
| `GET /api/token-transactions/paginated?chainId=&token=&limit=&cursor=` | Cursor-paginated token trades                     |                                60/min per key |

Limits can change and are not a service-level quota. Handle `429`, use backoff, cache stable data, and contact InkyPump before sustained high-volume use.

## Single-token identity

For integration routing, read at least:

```ts theme={null}
type LaunchIdentity = {
  chain_id: number
  address: `0x${string}`
  owner: `0x${string}`
  launchpad_version: "v1" | "v2"
  hook_address: `0x${string}` | null
  launch_id: string | number | null
  denomination_kind: string | null
  lifecycle_state: string | null
  finality_status: string | null
  chain_canonical: boolean | null
}
```

The API may add fields. Ignore unknown keys. Treat nullable metrics as unknown evidence, not zero.

## Batch lookup

Batch lookup is a `GET`, not a `POST`. Send at most 50 comma-separated addresses.

```bash theme={null}
curl "https://inkypump.com/api/tokens/batch?chainId=57073&addresses=0xAAA...,0xBBB..."
```

```json theme={null}
{
  "chainId": 57073,
  "tokens": {
    "0xaaa...": { "address": "0xaaa...", "ticker": "AAA" },
    "0xbbb...": null
  }
}
```

Keys are normalized addresses. A `null` value means that address was not found on the requested chain.

## Discovery after creation

After `LaunchCreated` is confirmed:

1. Show the transaction and token address immediately.
2. Poll `/api/token` with short exponential backoff.
3. If it returns `404`, keep the state as **confirmed, indexing**.
4. If the page reloads, resume from the saved transaction hash.
5. Never send a second `createLaunch` merely because indexing took longer than expected.

## Finality and reorgs

Useful fields include:

| Field                     | Meaning                                                 |
| ------------------------- | ------------------------------------------------------- |
| `chain_canonical`         | The indexed launch still belongs to the canonical chain |
| `finality_status`         | Indexer finality state for the launch                   |
| `block_number`            | Block that created the indexed record                   |
| `launch_block_hash`       | Block identity used to detect a reorg                   |
| `launch_log_index`        | Event position in the transaction/block                 |
| `metrics_as_of`           | Time through which metrics were computed                |
| `metrics_finality_status` | Finality state of the metric projection                 |

For accounting, wait for your chosen finality standard. For UI discovery, you may show a pending record, but label it.

## Units and nulls

* Contract amounts are integers in the asset's smallest unit.
* Native amounts use 18 decimals.
* Token and wrapper decimals come from their contract or the xStocks asset record.
* Fields ending in `_exact` are strings when precision would be lost in JSON numbers.
* USD values are valuation evidence, not executable token quotes.
* `null` means unavailable or not applicable. It never means zero.

For xStocks, keep `quote_valuation_status`, `quote_valuation_as_of`, and `quote_valuation_reference_at` with the displayed USD value.

## Retry policy

|                              Status | Action                                                              |
| ----------------------------------: | ------------------------------------------------------------------- |
|                               `200` | Accept and validate the response chain                              |
|                               `400` | Fix the request; do not retry unchanged                             |
| `404` just after a confirmed launch | Retry lookup with backoff                                           |
|                               `403` | Feature or origin policy rejected the request; do not loop          |
|                               `429` | Respect backoff and lower request rate                              |
|                      `500` or `503` | Retry reads with jitter; keep the last known UI state clearly dated |

## No public webhooks yet

InkyPump does not currently publish a supported third-party webhook contract. Use receipt-driven polling for creation and bounded API polling for discovery. Do not treat Discord or Telegram notifications as an integration feed.