# Charts

> Issue the short-lived tokens that authenticate the charts datafeed.

Price charts, the screener and wallet pages read from a separate datafeed service, not from the REST API. These endpoints issue the JWTs that service accepts.

A **chart token** is scoped to the mint of a launch the caller owns or holds a share on and authenticates the datafeed WebSocket for that mint. An **unscoped token** is issued to the account for the screener or the wallet reads. The web app decodes each token's `exp` claim to renew it before it lapses.

Base URL: `https://api-mig.proxima.tools`

## Endpoints

- `GET /charts/{launch_id}/subscribe`: Create a chart token
- `GET /charts/{audience}/token`: Create an unscoped datafeed token

### Create a chart token

`GET /charts/{launch_id}/subscribe`

Issues a datafeed token scoped to the mint of a launch the caller owns or holds a share on. (Bearer JWT)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: allowed.
- Retry: Safe to retry. Each call issues a new token and may register the token's pools with the indexer again; nothing else changes.

The token is a JWT whose `mint` claim names the launch's token; the web app uses it to authenticate the datafeed WebSocket for that mint and calls this endpoint again when a renewal is due. The call also registers the token's pools with the indexer.

The SDK retries when the response carries no `token` or the call fails, up to `maxRetries` times (default 5) with a linear backoff of 1 s, 2 s, 3 s... The datafeed provider passes `maxRetries = 0` and runs its own exponential backoff instead.

> A grantee whose share carries `launch.read` gets a token too. It expires 5 minutes after the call, or at the grant's expiry if that comes first; the owner's token lasts as long as a session.

> A launch still waiting for its deploy can fail for minutes; callers should retry with backoff rather than treat each failure as fatal.

#### Path parameters

- `launch_id` (string, required): The launch `ext_id`.

#### Returns 200 OK

- `ok` (boolean): `true` on success.
- `chain` (string): Chain ID of the launch.
- `mint` (string): Token mint or contract address the token is scoped to.
- `token` (string): Datafeed JWT carrying `mint` and `exp` claims. Valid for one week.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `invalid launch id format` | The launch ID is not a valid `ext_id`. | Pass the 15-digit launch `ext_id`. |
| 403 | `forbidden` | `this share does not carry 'launch.read'` | The caller reaches the launch through a share that does not carry `launch.read`. | Ask the owner to add `launch.read` to your grant. |
| 404 | `not_found` | `launch not found` | The launch does not exist, or the caller neither owns it nor holds a live share on it. | Check the `ext_id` against your own launches and [List launches shared with you](/reference/launch-sharing/#list-shared-launches). |
| 404 | `not_found` | `Token not launched yet` | The launch is on an EVM chain and its token is not deployed yet. | Request the token again with backoff once the deploy has landed. |

#### Example request

```bash
curl "https://api-mig.proxima.tools/charts/101920010239643/subscribe" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "ok": true,
  "chain": "sol",
  "mint": "Fe7dTUwYvLw7znvXqijANZgztiDVWiE4J3cjDs6RiaZ",
  "token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJtaW50IjoiRmU3ZFRVd1l2THc3em52WHFpakFOWmd6dGlEVldpRTRKM2NqRHM2UmlhWiIsImV4cCI6MTc5NDIxOTMwMH0.ZXhhbXBsZS1zaWduYXR1cmUtbm90LXZhbGlk"
}
```

### Create an unscoped datafeed token

`GET /charts/{audience}/token`

Issues a five-minute datafeed token to the account for the screener or the wallet reads. (Admin JWT · beta)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: allowed.
- Retry: Safe to retry. Each call issues a new token and counts toward the limit of 30 per minute.

The SDK throws when the response has no `token`, and defaults `expires_in` to `300` when it is missing. The app caches the token and fetches a new one 60 seconds before `exp`, or immediately when the datafeed answers 401.

> The screener and wallet pages are behind feature flags and are enabled by default only on the dev deployment.

#### Path parameters

- `audience` (enum, required): Datafeed audience the token is issued for. Possible values: `screener`, `wallet`.

#### Returns 200 OK

- `token` (string): Datafeed JWT.
- `expires_in` (integer): Lifetime in seconds.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 403 | `forbidden` | `the screener is admin-only` | `audience` is `screener` and the caller is not an admin. | Call it with an admin account's session. |
| 403 | `forbidden` | `the wallet explorer is admin-only` | `audience` is `wallet` and the caller is not an admin. | Call it with an admin account's session. |
| 429 | `too_many_requests` | `rate limit exceeded for screener_token, please retry later` | More than 30 tokens for this audience in a minute for this account. For `wallet`, the message names `wallet_token`. | Reuse the token until 60 seconds before its `exp`. |

#### Example request

```bash
curl "https://api-mig.proxima.tools/charts/screener/token" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3OTM2MTQ4MDB9.ZXhhbXBsZS1zaWduYXR1cmUtbm90LXZhbGlk",
  "expires_in": 300
}
```
