> For the complete documentation index, see [llms.txt](https://docs.alphagate.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.alphagate.io/developer-api/developer-api.md).

# API overview

Alphagate's data in your own bots, dashboards and scripts, billed per call in credits.

The Alphagate API gives your own bots, dashboards and scripts the data behind Alphagate, billed per call in credits.

## Quick start

1. Buy an API plan on the [Subscribe page](https://alphagate.io/subscribe) (**API** tab). [Plans and credits →](/developer-api/plans-and-credits.md)
2. **Generate Key** on the [API dashboard](https://alphagate.io/account/api). Anyone with the key can spend your credits, so keep it out of client-side code.
3. Send it in the `x-api-key` header:

```bash
curl -H "x-api-key: $ALPHAGATE_API_KEY" \
  "https://api.alphagate.io/api/v2/user/alpha?username=elonmusk"
```

The response (this is the API's own published example):

```json
{
  "message": "OK",
  "data": {
    "id": "44196397",
    "username": "elonmusk",
    "key_followers_count": 4450,
    "prev_usernames_count": 1,
    "prev_usernames": ["previous_handle"],
    "has_contracts": true,
    "contracts_count": 2,
    "contracts": ["0xdef...", "0xabc..."],
    "has_comms_created": false,
    "comms_created_count": 0
  },
  "credits": { "cost": 6, "remaining": 49994 }
}
```

## Common uses

| To find out                                                                                                                 | Call                                                             | Cost             |
| --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ---------------- |
| Whether an account is worth trusting, in one call: key followers, previous usernames, contracts posted, communities created | `/user/alpha`                                                    | 6 credits        |
| Who's in, and in what order                                                                                                 | `/user/key-followers?sort=oldest`                                | 4 credits        |
| What it posted and then deleted                                                                                             | `/user/deleted-tweets`                                           | 4 credits        |
| Every contract it has mentioned, with chain and ticker                                                                      | `/user/contracts`                                                | 2 credits        |
| Its first followers                                                                                                         | `/user/first-follows`                                            | 3 credits        |
| Live data from X without your own X access                                                                                  | `/x/user/overview`, `/x/user/latest-tweets`, `/x/user/followers` | from 0.1 credits |

Costs are today's; the [Endpoints](/developer-api/endpoints.md) page always has the current ones.

## Basics

|                         |                                                                    |
| ----------------------- | ------------------------------------------------------------------ |
| **Base URL**            | `https://api.alphagate.io/api/v2`                                  |
| **Authentication**      | `x-api-key: <your key>` header on every call                       |
| **Method**              | `GET` with query parameters                                        |
| **Identify an account** | `username` (without @) or `twitterId` (numeric)                    |
| **Response**            | `{ "message", "data", "credits": { "cost", "remaining" } }`        |
| **Rate limit**          | 180 requests per minute per API key, on every plan                 |
| **Paging**              | `page` and `limit` (default 20, at most 50) on endpoints that page |

The full list of endpoints, with parameters, costs and example responses, is on the [Endpoints](/developer-api/endpoints.md) page. A machine-readable description of every endpoint is at [`https://api.alphagate.io/api/info`](https://api.alphagate.io/api/info) (no key needed).

## Errors

| Status | Meaning                                                                                              |
| ------ | ---------------------------------------------------------------------------------------------------- |
| `400`  | A parameter is missing or malformed. Usernames are letters, digits and `_`; IDs are digits.          |
| `401`  | `Missing API key` or `Invalid API key`.                                                              |
| `402`  | `Insufficient credits`: your balance is lower than the most the call could cost. Nothing is charged. |
| `403`  | The account is suspended.                                                                            |
| `404`  | Alphagate doesn't track this account.                                                                |
| `429`  | Over 180 requests a minute. Wait and retry. Live X endpoints can also ask you to retry shortly.      |
| `500`  | Something went wrong on our side. Retry, and tell us if it keeps happening.                          |

Failed calls and empty results don't cost credits.

{% hint style="info" %}
Need more than the plans offer, or an endpoint we don't have yet? Talk to us on [Discord](https://discord.gg/alphagate) or [Telegram](https://t.me/alphagatesupport).
{% endhint %}