# X Tracker

> Follow X accounts in real time, organize them in lists, and research tweets for token deploys.

The X Tracker is an admin-only workspace that streams posts, follows and profile changes from a set of X accounts, so an operator can react to a tweet and deploy a token from it. One **shared session** tracks one set of accounts for every admin; each admin keeps their own **lists** (named subsets of those accounts) and their own settings document.

The live feed is a server-sent event stream. Saved tweets fill the feed on load. Around it, research endpoints relay third-party services through the backend: Frontrun for X search and profile reports, FxTwitter for single tweets, and Serper for Google image search, plus name/ticker suggestions and image analysis used by the deploy flow.

All endpoints require an admin account. The web app shows the page as **X Tracker** at `/tracker`.

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

## Endpoints

- `GET /tracker/stream`: Stream tracker events
- `GET /tracker/handles`: List tracked accounts
- `POST /tracker/handles`: Track an account
- `DELETE /tracker/handles/{handle}`: Stop tracking an account
- `GET /tracker/tweets`: List saved tweets
- `GET /tracker/settings`: Retrieve tracker settings
- `PUT /tracker/settings`: Save tracker settings
- `GET /tracker/lists`: List tracker lists
- `POST /tracker/lists`: Create a list
- `PATCH /tracker/lists/{list_id}`: Update a list
- `DELETE /tracker/lists/{list_id}`: Delete a list
- `GET /tracker/frontrun/search`: Search X posts
- `GET /tracker/frontrun/profile/{handle}/{report}`: Retrieve an X profile report
- `GET /tracker/frontrun/old-username/{handle}`: Look up previous owners of a handle
- `GET /tracker/frontrun/credits`: Retrieve Frontrun credits
- `POST /tracker/suggest`: Suggest token names for a tweet
- `POST /tracker/vision`: Analyze a tweet image
- `GET /tracker/images`: Search web images
- `GET /tracker/fx/{tweet_id}`: Retrieve a tweet

## The Tracked handle object

An X account followed by the shared tracker session.

- `handle` (string): X handle, lowercase, without `@`.
- `displayName` (string | null): Account display name.
- `isActive` (boolean): Whether the session is currently tracking the account.
- `twitterUserId` (string | null): Numeric X user ID as a string.

```json
{
  "handle": "examplecaller",
  "displayName": "Example Caller",
  "isActive": true,
  "twitterUserId": "1580000000000000001"
}
```

## The Tracker list object

A named subset of the tracked accounts, shown as its own feed. Lists belong to the caller.

- `id` (string): Unique identifier.
- `name` (string): List name.
- `handles` (array<string>): Handles in the list.
- `position` (integer): Sort position; the app orders lists by it.
- `icon` (string | null): Icon name from the tracker's icon set.
- `color` (string | null): Color as `#rrggbb`.

```json
{
  "id": "67744a28-e685-49cd-a56b-803b8e647080",
  "name": "Callers",
  "handles": [
    "examplecaller",
    "demo_trader"
  ],
  "position": 0,
  "icon": null,
  "color": "#4f8cff"
}
```

## The Saved tweet object

A tweet event stored by the tracker: the realtime payload as received, with its delivery time and suggestions.

- `event` (object): Raw realtime payload (the `d` of a stream `event` message).
- `received_at` (integer): Time the backend received the event, in Unix milliseconds.
- `deleted` (boolean): Whether the tweet was deleted since.
- `suggestions` (array<object> | null): [Suggestions](#object-suggestion) for the tweet; `null` until they are made.

```json
{
  "event": {
    "event": "twitter.post.new",
    "event_time": 1793614504000,
    "task_info": {
      "handle": "examplecaller"
    },
    "data": {
      "id": "1852200000000000001",
      "type": "post",
      "text": "the otter is coming $OTTER",
      "author": {
        "id": "1580000000000000001",
        "handle": "examplecaller",
        "name": "Example Caller"
      },
      "created_at": 1793614500000,
      "media": [],
      "cashtags": [
        "OTTER"
      ]
    }
  },
  "received_at": 1793614504000,
  "deleted": false,
  "suggestions": [
    {
      "name": "Moon Otter",
      "symbol": "OTTER",
      "image": null
    }
  ]
}
```

## The Suggestion object

A token name and ticker proposed for a tweet.

- `name` (string): Token name.
- `symbol` (string): Ticker.
- `image` (string | null): Image URL to use, or `null`.

```json
{
  "name": "Moon Otter",
  "symbol": "OTTER",
  "image": null
}
```

### Stream tracker events

`GET /tracker/stream`

Opens a server-sent event stream of the shared tracker session. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: allowed.
- Retry: Safe to retry.

The response is `text/event-stream`. Events are separated by a blank line (`\n\n`); the client keeps only `data:` lines, strips the prefix, joins multi-line data with `\n`, and parses the result as JSON. Each message has a `type`:

- `status`: session state, with `status`, `error`, `latency` and `session`.
- `event`: one realtime event in `d`. `d.event` is `twitter.post.new`, `twitter.post.update`, `twitter.following.new`, `twitter.following.removed`, `twitter.follower.new`, `twitter.profile.update` or `twitter.tweet.deleted`; `d.task_info.handle` names the tracked account and `d.data` carries the event data.
- `handles`: the tracked set changed; reload [List tracked accounts](#list-handles).
- `suggestions`: name/ticker suggestions ready for `tweet_id`.
- `lagged`: `skipped` events were dropped.

The SDK makes a raw `fetch` with the bearer token and returns the `Response`; the caller reads and closes the body. On 401 or 403 the app stops and reports that the tracker is restricted to admins. On any other failure or end of stream it reconnects with exponential backoff capped at 30 seconds.

> This call bypasses the SDK transport: it gets no automatic 2FA retry or session-revocation handling. It still sends `Authorization` and `X-Sent-At`.

#### Returns 200 OK

A stream of `data:` events, each a JSON message.

- `type` (enum): Message type. Possible values: `status`, `event`, `handles`, `suggestions`, `lagged`.
- `status` (enum): On `status`: state of the upstream session. Possible values: `idle`, `connecting`, `authenticating`, `connected`, `reconnecting`, `error`.
- `error` (string | null): On `status`: error message, if any.
- `latency` (number | null): On `status`: latency reported by the session.
- `session` (object | null): On `status`: session details.
  - `modules` (array<string>): Modules enabled on the session.
  - `handles` (integer | null): Accounts tracked.
  - `maxHandles` (integer | null): Maximum accounts the session can track.
- `d` (object): On `event`: the raw realtime payload.
  - `event` (string): Event name, e.g. `twitter.post.new`.
  - `event_id` (string): Event identifier.
  - `event_time` (integer): Event time in Unix milliseconds.
  - `task_info` (object): `{ handle }` of the tracked account.
  - `data` (object): Event data: the tweet, the followed account, the profile change or the deleted tweet.
  - `replayed` (boolean): The event is a replay; the app does not notify for it.
  - `delayed` (boolean): The event arrived late.
- `tweet_id` (string): On `suggestions`: the tweet the suggestions are for.
- `suggestions` (array<object>): On `suggestions`: [Suggestion](#object-suggestion) objects.
- `skipped` (integer): On `lagged`: number of events skipped. The app ignores this message.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 403 | `forbidden` | `admin role required` | The caller is not an admin. The web app stops reconnecting on this status, as it does on 401. | Call it with an admin account's session. |
| 422 | `upstream_failure` | `xanguard api issue: XANGUARD_API_KEY is not configured` | The server has no Xanguard key, so there is no session to stream. | Set `XANGUARD_API_KEY` on the server, or retry later. |

#### Example request

```bash
curl "https://api-mig.proxima.tools/tracker/stream" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```text
data: {"type":"status","status":"connected","error":null,"latency":182,"session":{"modules":[],"handles":48,"maxHandles":200}}

data: {"type":"event","d":{"event":"twitter.post.new","event_time":1793614504000,"task_info":{"handle":"examplecaller"},"data":{"id":"1852200000000000001","type":"post","text":"the otter is coming $OTTER","author":{"handle":"examplecaller"},"created_at":1793614500000,"cashtags":["OTTER"]}}}

data: {"type":"suggestions","tweet_id":"1852200000000000001","suggestions":[{"name":"Moon Otter","symbol":"OTTER","image":null}]}


```

### List tracked accounts

`GET /tracker/handles`

Lists the X accounts followed by the shared tracker session. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: allowed.
- Retry: Safe to retry.

The SDK returns the `handles` array.

#### Returns 200 OK

Returns a list of [Tracked handle](#object-tracked-handle) objects.

- `handles` (array<object>): [Tracked handle](#object-tracked-handle) objects.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 403 | `forbidden` | `admin role required` | The caller is not an admin. | Call it with an admin account's session. |
| 422 | `upstream_failure` | `xanguard api issue: XANGUARD_API_KEY is not configured` | The server has no Xanguard key, or the Xanguard API failed. | Set `XANGUARD_API_KEY` on the server, or retry later. |

#### Example request

```bash
curl "https://api-mig.proxima.tools/tracker/handles" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "handles": [
    {
      "handle": "examplecaller",
      "displayName": "Example Caller",
      "isActive": true,
      "twitterUserId": "1580000000000000001"
    },
    {
      "handle": "demo_trader",
      "displayName": null,
      "isActive": true,
      "twitterUserId": null
    }
  ]
}
```

### Track an account

`POST /tracker/handles`

Adds an X account to the shared tracker session. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. A repeat answers 409 once the account is tracked; [List tracked accounts](/reference/tracker/#list-handles) shows the current set.

The web app normalizes input before sending: it strips a leading `@` and an `x.com` or `twitter.com` URL prefix, drops anything after `/`, `?` or `#`, and lowercases. The SDK returns the stored `handle`. Bulk import sends one request per handle.

#### Body parameters

- `handle` (string, required): X handle, without `@`.

#### Returns 200 OK

- `handle` (string): Handle as stored.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `Enter a valid handle` | `handle` does not reduce to an X handle of 1 to 50 letters, digits or `_`. | Send `@name`, `name` or an `x.com` profile link. |
| 400 | `bad_request` | `<xanguard_error>` | Xanguard refused the handle, with its own message. Bulk import skips it and continues. |  |
| 403 | `forbidden` | `<xanguard_error>` | The tracking limit of the Xanguard plan is reached, with Xanguard's own message. Bulk import stops here. | Stop tracking an account with [Stop tracking an account](/reference/tracker/#remove-handle) first. |
| 403 | `forbidden` | `admin role required` | The caller is not an admin. | Call it with an admin account's session. |
| 404 | `not_found` | `<xanguard_error>` | Xanguard does not know this X account. Bulk import skips it and continues. | Check the handle on X. |
| 409 | `conflict` | `<xanguard_error>` | The account is already tracked. Bulk import skips it and continues. | Nothing to do: the account is already tracked. |
| 422 | `upstream_failure` | `xanguard api issue: XANGUARD_API_KEY is not configured` | The server has no Xanguard key, or the Xanguard API failed. | Set `XANGUARD_API_KEY` on the server, or retry later. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/tracker/handles" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "handle": "demo_trader"
}'
```

#### Example response

```json
{
  "handle": "demo_trader"
}
```

### Stop tracking an account

`DELETE /tracker/handles/{handle}`

Removes an X account from the shared tracker session. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. A repeat after a success may answer an error relayed from Xanguard; [List tracked accounts](/reference/tracker/#list-handles) shows the current set.

#### Path parameters

- `handle` (string, required): X handle, without `@`.

#### Returns 200 OK

The web app does not read the response body.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `Enter a valid handle` | `handle` is not a valid X handle. | Send `@name`, `name` or an `x.com` profile link. |
| 403 | `forbidden` | `admin role required` | The caller is not an admin. | Call it with an admin account's session. |
| 422 | `upstream_failure` | `xanguard api issue: XANGUARD_API_KEY is not configured` | The server has no Xanguard key, or the Xanguard API failed. | Set `XANGUARD_API_KEY` on the server, or retry later. |

#### Example request

```bash
curl -X DELETE "https://api-mig.proxima.tools/tracker/handles/demo_trader" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{}
```

### List saved tweets

`GET /tracker/tweets`

Returns stored tweets of the given accounts, used to fill the feed on load. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: allowed.
- Retry: Safe to retry.

The web app requests each viewed account once, in batches of 40 handles with `per_handle=100`. The SDK returns the `tweets` array. Saved suggestions are merged into the feed.

#### Query parameters

- `handles` (string, optional): Comma-separated handles.
- `per_handle` (integer, optional): Maximum tweets per handle.
- `limit` (integer, optional): Maximum tweets in total.

#### Returns 200 OK

Returns a list of [Saved tweet](#object-saved-tweet) objects.

- `tweets` (array<object>): [Saved tweet](#object-saved-tweet) objects.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 403 | `forbidden` | `admin role required` | The caller is not an admin. The app stays silent instead of showing an error. | Call it with an admin account's session. |

#### Example request

```bash
curl "https://api-mig.proxima.tools/tracker/tweets?handles=examplecaller%2Cdemo_trader&per_handle=100" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "tweets": [
    {
      "event": {
        "event": "twitter.post.new",
        "event_time": 1793614504000,
        "task_info": {
          "handle": "examplecaller"
        },
        "data": {
          "id": "1852200000000000001",
          "type": "post",
          "text": "the otter is coming $OTTER",
          "author": {
            "id": "1580000000000000001",
            "handle": "examplecaller"
          },
          "created_at": 1793614500000,
          "cashtags": [
            "OTTER"
          ]
        }
      },
      "received_at": 1793614504000,
      "deleted": false,
      "suggestions": null
    }
  ]
}
```

### Retrieve tracker settings

`GET /tracker/settings`

Returns the caller's saved tracker settings document. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: allowed.
- Retry: Safe to retry.

The document is free-form JSON owned by the client. The web app stores `feed` (`sound`, `showMedia`, `detectVision`, `maxDepth`), per-account `prefs`, keyword `alerts`, `activeList`, `defaultList`, `deploy` presets and `layout`. The SDK returns `settings`. If loading fails, the app disables saving so stored settings are never overwritten with defaults.

#### Returns 200 OK

- `settings` (object | null): Saved document, or `null` when nothing is saved.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 403 | `forbidden` | `admin role required` | The caller is not an admin. | Call it with an admin account's session. |

#### Example request

```bash
curl "https://api-mig.proxima.tools/tracker/settings" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "settings": {
    "feed": {
      "sound": true,
      "showMedia": true,
      "detectVision": false,
      "maxDepth": 2
    },
    "activeList": "67744a28-e685-49cd-a56b-803b8e647080",
    "alerts": {
      "alerts": [],
      "desktop": false
    }
  }
}
```

### Save tracker settings

`PUT /tracker/settings`

Replaces the caller's tracker settings document. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. The body replaces the saved settings whole.

The web app saves 800 ms after the last change, and only when the document differs from the last saved copy.

#### Body parameters

- `settings` (object, required): The full settings document.

#### Returns 200 OK

The web app does not read the response body.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `settings must be an object` | `settings` is not a JSON object. | Send `settings` as an object. |
| 400 | `bad_request` | `settings are too large` | `settings` is larger than 256 KB once serialized. | Trim the settings below 256 KB. |
| 403 | `forbidden` | `admin role required` | The caller is not an admin. | Call it with an admin account's session. |

#### Example request

```bash
curl -X PUT "https://api-mig.proxima.tools/tracker/settings" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "settings": {
    "feed": {
      "sound": false,
      "showMedia": true,
      "detectVision": true,
      "maxDepth": 3
    },
    "activeList": null
  }
}'
```

#### Example response

```json
{}
```

### List tracker lists

`GET /tracker/lists`

Lists the caller's tracker lists. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: allowed.
- Retry: Safe to retry.

The SDK returns the `lists` array; the app sorts it by `position`.

#### Returns 200 OK

Returns a list of [Tracker list](#object-tracker-list) objects.

- `lists` (array<object>): [Tracker list](#object-tracker-list) objects.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 403 | `forbidden` | `admin role required` | The caller is not an admin. | Call it with an admin account's session. |

#### Example request

```bash
curl "https://api-mig.proxima.tools/tracker/lists" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "lists": [
    {
      "id": "67744a28-e685-49cd-a56b-803b8e647080",
      "name": "Callers",
      "handles": [
        "examplecaller",
        "demo_trader"
      ],
      "position": 0,
      "icon": null,
      "color": "#4f8cff"
    }
  ]
}
```

### Create a list

`POST /tracker/lists`

Creates a tracker list from a name and a set of tracked handles. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Check before retrying. A repeat creates a second list with the same name. Look for it in [List tracker lists](/reference/tracker/#list-lists) first.

#### Body parameters

- `name` (string, required): List name.
- `handles` (array<string>, required): Handles in the list.
- `icon` (string | null, optional): Icon name.
- `color` (string | null, optional): Color as `#rrggbb`.

#### Returns 200 OK

Returns the created [Tracker list](#object-tracker-list).

- `list` (object): The [Tracker list](#object-tracker-list).

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `At most 50 lists` | The caller already has 50 lists. | Free a slot with [Delete a list](/reference/tracker/#delete-list) first. |
| 400 | `bad_request` | `List name must be 1 to 40 characters` | `name` is empty or longer than 40 characters. | Send a name of 1 to 40 characters. |
| 400 | `bad_request` | `Invalid list icon` | `icon` is longer than 32 characters or has characters other than ASCII letters and digits. | Send an icon name from the app's icon set, or an empty string to clear it. |
| 400 | `bad_request` | `List color must be #rrggbb` | `color` is not a `#rrggbb` hex color. | Send a color such as `#1d9bf0`, or an empty string to clear it. |
| 400 | `bad_request` | `Enter a valid handle` | An entry in `handles` is not a valid X handle. | Send `@name`, `name` or an `x.com` profile link. |
| 403 | `forbidden` | `admin role required` | The caller is not an admin. | Call it with an admin account's session. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/tracker/lists" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Callers",
  "handles": [
    "examplecaller",
    "demo_trader"
  ],
  "color": "#4f8cff"
}'
```

#### Example response

```json
{
  "list": {
    "id": "67744a28-e685-49cd-a56b-803b8e647080",
    "name": "Callers",
    "handles": [
      "examplecaller",
      "demo_trader"
    ],
    "position": 0,
    "icon": null,
    "color": "#4f8cff"
  }
}
```

### Update a list

`PATCH /tracker/lists/{list_id}`

Updates a list's name, handles, position, icon or color. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry.

Only the fields sent change. To clear `icon` or `color`, send an empty string; the SDK turns a `null` into `""`.

#### Path parameters

- `list_id` (string, required): List ID.

#### Body parameters

- `name` (string, optional): New name.
- `handles` (array<string>, optional): New set of handles.
- `position` (integer, optional): New sort position.
- `icon` (string, optional): Icon name, or `""` to clear.
- `color` (string, optional): Color as `#rrggbb`, or `""` to clear.

#### Returns 200 OK

Returns the updated [Tracker list](#object-tracker-list).

- `list` (object): The [Tracker list](#object-tracker-list).

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `List name must be 1 to 40 characters` | `name` is empty or longer than 40 characters. | Send a name of 1 to 40 characters. |
| 400 | `bad_request` | `Invalid list icon` | `icon` is longer than 32 characters or has characters other than ASCII letters and digits. | Send an icon name from the app's icon set, or an empty string to clear it. |
| 400 | `bad_request` | `List color must be #rrggbb` | `color` is not a `#rrggbb` hex color. | Send a color such as `#1d9bf0`, or an empty string to clear it. |
| 400 | `bad_request` | `Enter a valid handle` | An entry in `handles` is not a valid X handle. | Send `@name`, `name` or an `x.com` profile link. |
| 403 | `forbidden` | `admin role required` | The caller is not an admin. | Call it with an admin account's session. |
| 404 | `not_found` | `List not found` | No list with this ID belongs to the caller. | Pick a list ID from [List tracker lists](/reference/tracker/#list-lists). |

#### Example request

```bash
curl -X PATCH "https://api-mig.proxima.tools/tracker/lists/67744a28-e685-49cd-a56b-803b8e647080" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Top callers",
  "color": ""
}'
```

#### Example response

```json
{
  "list": {
    "id": "67744a28-e685-49cd-a56b-803b8e647080",
    "name": "Top callers",
    "handles": [
      "examplecaller",
      "demo_trader"
    ],
    "position": 0,
    "icon": null,
    "color": null
  }
}
```

### Delete a list

`DELETE /tracker/lists/{list_id}`

Deletes one of the caller's tracker lists. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. A repeat answers 404 once the list is gone.

Tracked accounts are not affected.

#### Path parameters

- `list_id` (string, required): List ID.

#### Returns 200 OK

The web app does not read the response body.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 403 | `forbidden` | `admin role required` | The caller is not an admin. | Call it with an admin account's session. |
| 404 | `not_found` | `List not found` | No list with this ID belongs to the caller. | Pick a list ID from [List tracker lists](/reference/tracker/#list-lists). |

#### Example request

```bash
curl -X DELETE "https://api-mig.proxima.tools/tracker/lists/67744a28-e685-49cd-a56b-803b8e647080" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{}
```

### Search X posts

`GET /tracker/frontrun/search`

Searches X through Frontrun, newest first. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: allowed.
- Retry: Safe to retry.

Accepts keywords, contract addresses and X operators such as `from:` or `min_faves:`. The backend relays Frontrun's envelope unchanged: check `status` before reading `data`. The app caches each page for 60 seconds.

> Each search costs 3 Frontrun credits.

#### Query parameters

- `q` (string, required): Search query.
- `page_size` (integer, optional): Results per page. The app sends `20`.
- `cursor` (string, optional): `nextCursor` from the previous page.

#### Returns 200 OK

- `status` (boolean): `false` when Frontrun reports a failure, with `message`.
- `message` (string): Frontrun's message.
- `data` (object): Search page.
  - `tweets` (array<object>): Raw tweets with `tweet_id`, `url`, `screen_name`, `text`, `created_at`, engagement counts, `user_info`, `media` and `entities`.
  - `nextCursor` (string | null): Cursor for the next page, or `null`.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `q is required` | `q` is empty. | Send a search query in `q`. |
| 401 |  |  | Frontrun rejected the server's API key. Relayed with Frontrun's own body, without a Proxima `code`. | Check the Frontrun key configured on the server. |
| 403 | `forbidden` | `admin role required` | The caller is not an admin. | Call it with an admin account's session. |
| 403 |  |  | Frontrun rejected the server's API key. Relayed with Frontrun's own body, without a Proxima `code`. | Check the Frontrun key configured on the server. |
| 422 | `upstream_failure` | `frontrun api issue: FRONTRUN_API_KEY is not configured` | The server has no Frontrun key, or the call to Frontrun failed in transit. | Set `FRONTRUN_API_KEY` on the server, or retry later. |
| 429 |  |  | Frontrun rate limit (60 requests per minute). Relayed with Frontrun's own body, without a Proxima `code`. | Wait a minute before the next Frontrun call. |

#### Example request

```bash
curl "https://api-mig.proxima.tools/tracker/frontrun/search?q=%24OTTER%20min_faves%3A50" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "status": true,
  "data": {
    "tweets": [
      {
        "tweet_id": "1852200000000000001",
        "url": "https://x.com/examplecaller/status/1852200000000000001",
        "screen_name": "examplecaller",
        "text": "the otter is coming $OTTER",
        "created_at": "2026-11-02T10:15:00.000Z",
        "favorites": 120,
        "retweets": 14,
        "replies": 9,
        "quotes": 2,
        "views": "18200",
        "user_info": {
          "screen_name": "examplecaller",
          "name": "Example Caller",
          "rest_id": "1580000000000000001",
          "followers_count": 48210,
          "avatar": "https://pbs.twimg.com/profile_images/example.jpg",
          "verified": true
        },
        "media": []
      }
    ],
    "nextCursor": "c2VhcmNoLWN1cnNvci0y"
  }
}
```

### Retrieve an X profile report

`GET /tracker/frontrun/profile/{handle}/{report}`

Returns a Frontrun report on an X account: its profile, its smart followers, or the contract addresses it posted. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: allowed.
- Retry: Safe to retry.

The `data` shape depends on `report`:

- `info`: profile with `twitterId`, `name`, `twitterUsername`, `bio`, `profilePhoto`, `followersCount`, `followingsCount` and labels, or `null`.
- `smart-followers`: `{ smartFollowers, totalCount }`.
- `tweets-with-ca`: `{ topUndeletedTweets, topDeletedTweets, undeletedCACount, deletedCACount, undeletedTweetCount, deletedTweetCount }`, including tweets that were later deleted.

The app caches each report for 10 minutes so reopening a profile does not spend credits twice.

> Credit cost per report: `info` 10, `smart-followers` 10, `tweets-with-ca` 25.

#### Path parameters

- `handle` (string, required): X handle, without `@`.
- `report` (enum, required): Report to fetch. Possible values: `info`, `smart-followers`, `tweets-with-ca`.

#### Returns 200 OK

- `status` (boolean): `false` when Frontrun reports a failure.
- `message` (string): Frontrun's message.
- `data` (any): Report payload; see above.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `Enter a valid handle` | `handle` is not a valid X handle. | Send `@name`, `name` or an `x.com` profile link. |
| 403 | `forbidden` | `admin role required` | The caller is not an admin. | Call it with an admin account's session. |
| 404 | `not_found` | `Unknown profile endpoint` | `report` is not `info`, `smart-followers` or `tweets-with-ca`. | Use `info`, `smart-followers` or `tweets-with-ca`. |
| 422 | `upstream_failure` | `frontrun api issue: FRONTRUN_API_KEY is not configured` | The server has no Frontrun key, or the call to Frontrun failed in transit. | Set `FRONTRUN_API_KEY` on the server, or retry later. |
| 429 |  |  | Frontrun rate limit (60 requests per minute). Relayed with Frontrun's own body, without a Proxima `code`. | Wait a minute before the next Frontrun call. |

#### Example request

```bash
curl "https://api-mig.proxima.tools/tracker/frontrun/profile/examplecaller/info" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "status": true,
  "data": {
    "twitterId": "1580000000000000001",
    "name": "Example Caller",
    "twitterUsername": "examplecaller",
    "bio": "memes and charts",
    "profilePhoto": null,
    "followersCount": 48210,
    "followingsCount": 812,
    "primaryLabel": null
  }
}
```

### Look up previous owners of a handle

`GET /tracker/frontrun/old-username/{handle}`

Returns the X accounts that used this handle before renaming away from it. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: allowed.
- Retry: Safe to retry.

#### Path parameters

- `handle` (string, required): X handle, without `@`.

#### Returns 200 OK

- `status` (boolean): `false` when Frontrun reports a failure.
- `message` (string): Frontrun's message.
- `data` (object): Lookup result.
  - `found` (boolean): Whether earlier owners were found.
  - `profiles` (array<object>): Earlier accounts. The app reads `twitterUsername` (or `username`, `twitter`), `name` and `profilePhoto`.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `Enter a valid handle` | `handle` is not a valid X handle. | Send `@name`, `name` or an `x.com` profile link. |
| 403 | `forbidden` | `admin role required` | The caller is not an admin. | Call it with an admin account's session. |
| 422 | `upstream_failure` | `frontrun api issue: FRONTRUN_API_KEY is not configured` | The server has no Frontrun key, or the call to Frontrun failed in transit. | Set `FRONTRUN_API_KEY` on the server, or retry later. |

#### Example request

```bash
curl "https://api-mig.proxima.tools/tracker/frontrun/old-username/examplecaller" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "status": true,
  "data": {
    "found": true,
    "profiles": [
      {
        "twitterUsername": "otter_archive",
        "name": "Otter Archive",
        "profilePhoto": null
      }
    ]
  }
}
```

### Retrieve Frontrun credits

`GET /tracker/frontrun/credits`

Returns the Frontrun credit balance of the tracker's API key. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: allowed.
- Retry: Safe to retry.

#### Returns 200 OK

- `status` (boolean): `false` when Frontrun reports a failure.
- `data` (object): Credit balance.
  - `currentPoints` (number): Credits left.
  - `totalCredits` (string): Total credits, as a numeric string.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 403 | `forbidden` | `admin role required` | The caller is not an admin. | Call it with an admin account's session. |
| 422 | `upstream_failure` | `frontrun api issue: FRONTRUN_API_KEY is not configured` | The server has no Frontrun key, or the call to Frontrun failed in transit. | Set `FRONTRUN_API_KEY` on the server, or retry later. |

#### Example request

```bash
curl "https://api-mig.proxima.tools/tracker/frontrun/credits" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "status": true,
  "data": {
    "currentPoints": 41820,
    "totalCredits": "50000"
  }
}
```

### Suggest token names for a tweet

`POST /tracker/suggest`

Returns name and ticker picks for a tweet, to prefill a token deploy. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. Picks are made once per tweet `id` and saved; a repeat returns the saved picks.

The web app asks for three picks per tweet, once the tweet card scrolls into view, and caches them for the session. The SDK returns the `suggestions` array.

> The body is typed as a free-form object in the SDK; the fields above are what the web app sends.

#### Body parameters

- `id` (string, optional): Tweet ID.
- `text` (string, optional): Tweet text.
- `handle` (string, optional): Author handle.
- `followers` (integer | null, optional): Author follower count.
- `media` (array<string>, optional): Photo URLs.
- `posters` (array<string>, optional): Video poster URLs.
- `avatar` (string | null, optional): Author avatar URL.
- `quoted_handle` (string | null, optional): Handle of the quoted tweet's author.
- `quoted_text` (string | null, optional): Text of the quoted tweet.
- `quoted_media` (array<string>, optional): Photo URLs of the quoted tweet.
- `reply_to` (string | null, optional): Handle the tweet replies to.
- `cashtags` (array<string>, optional): Cashtags in the text, without `$`.

#### Returns 200 OK

Returns a list of [Suggestion](#object-suggestion) objects.

- `suggestions` (array<object>): [Suggestion](#object-suggestion) objects.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 403 | `forbidden` | `admin role required` | The caller is not an admin. | Call it with an admin account's session. |
| 422 | `unprocessable` | `Trench examples unusable (<error>)` | The examples the suggestions rely on cannot be loaded. | Check the trench examples on the server (`TRENCH_AI_DIR`). |
| 422 | `upstream_failure` | `gemini api issue: GEMINI_API_KEY is not configured` | The server has no Gemini key. | Set `GEMINI_API_KEY` on the server. |
| 422 | `upstream_failure` | `gemini api issue: no suggestions` | Gemini returned no usable suggestion for this tweet. | Retry, or name the token by hand. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/tracker/suggest" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "1852200000000000001",
  "text": "the otter is coming $OTTER",
  "handle": "examplecaller",
  "followers": 48210,
  "media": [],
  "posters": [],
  "avatar": null,
  "quoted_handle": null,
  "quoted_text": null,
  "quoted_media": [],
  "reply_to": null,
  "cashtags": [
    "OTTER"
  ]
}'
```

#### Example response

```json
{
  "suggestions": [
    {
      "name": "Moon Otter",
      "symbol": "OTTER",
      "image": null
    },
    {
      "name": "Otter Coming",
      "symbol": "OTCOME",
      "image": null
    },
    {
      "name": "Otter",
      "symbol": "OTR",
      "image": null
    }
  ]
}
```

### Analyze a tweet image

`POST /tracker/vision`

Detects the subjects and legible texts in an image, with their positions. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. Results are cached per image for an hour.

Send either `url` (an X media URL) or `image` (a `data:image/...;base64,` URL for an image only the browser holds, such as a captured video frame). The SDK picks the field from the source string. Boxes are in percent of the image, from 0 to 100. The app draws them over tweet images when **detect vision** is on.

#### Body parameters

- `url` (string, optional): X media URL. Send this or `image`.
- `image` (string, optional): Image as a `data:` URL. Send this or `url`.

#### Returns 200 OK

- `subjects` (array<object>): Detected subjects.
  - `label` (string): What the subject is.
  - `box` (object): `{ x, y, width, height }` in percent of the image.
- `texts` (array<object>): Legible texts.
  - `text` (string): Text as read.
  - `name` (string): Token name derived from the text.
  - `symbol` (string): Ticker derived from the text.
  - `box` (object): `{ x, y, width, height }` in percent of the image.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `Send either url or image` | The body has both `url` and `image`, or neither. | Send exactly one of `url` and `image`. |
| 400 | `bad_request` | `Invalid image url` | `url` is not a valid URL. | Send the full `https` URL of the image. |
| 400 | `bad_request` | `Only X media images can be analysed` | `url` is not an `https` image on `pbs.twimg.com`, `abs.twimg.com` or `video.twimg.com`. | Send an X media URL, or the image itself in `image`. |
| 400 | `bad_request` | `Invalid image data` | `image` is not a base64 `data:` URL. | Send `image` as `data:image/<type>;base64,<data>`. |
| 403 | `forbidden` | `admin role required` | The caller is not an admin. | Call it with an admin account's session. |
| 422 | `unprocessable` | `Not an image` | The URL or the data does not hold an image. | Send an image. |
| 422 | `unprocessable` | `Image is too large` | The image is larger than 8 MB. | Send an image under 8 MB. |
| 422 | `upstream_failure` | `x media api issue: image answered <status>` | The X media host answered an error status for `url`. | Check that the image still exists on X. |
| 422 | `upstream_failure` | `gemini api issue: GEMINI_API_KEY is not configured` | The server has no Gemini key. | Set `GEMINI_API_KEY` on the server. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/tracker/vision" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://pbs.twimg.com/media/example.jpg"
}'
```

#### Example response

```json
{
  "subjects": [
    {
      "label": "otter",
      "box": {
        "x": 22.5,
        "y": 10,
        "width": 48,
        "height": 70
      }
    }
  ],
  "texts": [
    {
      "text": "OTTER SZN",
      "name": "Otter Season",
      "symbol": "OTTER",
      "box": {
        "x": 30,
        "y": 82,
        "width": 40,
        "height": 10
      }
    }
  ]
}
```

### Search web images

`GET /tracker/images`

Searches Google Images through Serper, to pick a deploy image. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: allowed.
- Retry: Safe to retry.

Returns Serper's payload as relayed by the backend. The app reads `imageUrl`, `title`, `thumbnailUrl`, `imageWidth`, `imageHeight` and `source` (or `domain`) from each image, and caches results per query for the session.

#### Query parameters

- `q` (string, required): Search query.

#### Returns 200 OK

- `images` (array<object>): Image results.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `Query must be 1-120 characters` | `q` is empty or longer than 120 characters. | Send a query of 1 to 120 characters. |
| 403 | `forbidden` | `admin role required` | The caller is not an admin. | Call it with an admin account's session. |
| 422 | `upstream_failure` | `serper api issue: SERPER_API_KEY is not configured` | The server has no Serper key. | Set `SERPER_API_KEY` on the server. |
| 422 | `upstream_failure` | `serper api issue: Image search failed (<status>)` | Serper answered an error status. | Retry in a few minutes. |

#### Example request

```bash
curl "https://api-mig.proxima.tools/tracker/images?q=sea%20otter%20meme" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "images": [
    {
      "title": "Sea otter floating",
      "imageUrl": "https://images.example.com/otter.jpg",
      "imageWidth": 1200,
      "imageHeight": 800,
      "thumbnailUrl": "https://images.example.com/otter-thumb.jpg",
      "source": "example.com"
    }
  ]
}
```

### Retrieve a tweet

`GET /tracker/fx/{tweet_id}`

Returns a public tweet's details from FxTwitter, used to walk reply threads and quote chains. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: allowed.
- Retry: Safe to retry.

The backend relays FxTwitter's status payload. The app reads `id`, `text`, `url`, `author` (`screen_name`, `name`, `avatar_url`, `followers`), `media.all`, `created_timestamp` (Unix seconds), `replying_to`, `replying_to_status` and `quote`. Requests run at most 4 at a time and results are cached for the session.

#### Path parameters

- `tweet_id` (string, required): Tweet ID.

#### Returns 200 OK

- `tweet` (object): FxTwitter tweet object.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `Invalid tweet id` | `tweet_id` is not 1 to 25 digits. | Pass the numeric ID from the tweet URL. |
| 403 | `forbidden` | `admin role required` | The caller is not an admin. | Call it with an admin account's session. |
| 404 |  |  | The tweet was deleted or does not exist. Relayed from FxTwitter with its own body, without a Proxima `code`; the backend caches the miss for 10 minutes and the app caches it too. |  |
| 422 | `upstream_failure` | `fxtwitter api issue: <error>` | FxTwitter could not be reached. | Retry in a few minutes. |

#### Example request

```bash
curl "https://api-mig.proxima.tools/tracker/fx/1852200000000000001" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "tweet": {
    "id": "1852200000000000001",
    "url": "https://x.com/examplecaller/status/1852200000000000001",
    "text": "the otter is coming $OTTER",
    "author": {
      "screen_name": "examplecaller",
      "name": "Example Caller",
      "avatar_url": null,
      "followers": 48210
    },
    "created_timestamp": 1793614500,
    "replying_to": null,
    "replying_to_status": null
  }
}
```
