# Overview

## Indexify API Overview

The Indexify API provides programmatic access to the Indexify platform — a token trading and stack indexing system on Solana. Use it to manage accounts, discover and trade stacks, track portfolios, and access market data.

### Base URL

All endpoints are accessed under this base URL. Most endpoints use `POST` with a JSON body. The specific operation is selected via the `?action=` query parameter.

### Authentication

Pass your API key in the `X-API-KEY` header on every authenticated request:

```
X-API-KEY: ix_your_api_key_here
```

API keys use the `ix_` prefix. To obtain a key, contact the Indexify team with your Indexify username.

Some endpoints are publicly accessible without authentication. When authentication is optional, providing a key enriches the response with user-specific data (e.g., `is_following`, `user_has_held`).

### Request Format

* **Content-Type:** `application/json`
* **Method:** `POST` for most endpoints; `GET` for transaction history, leaderboard, and referral data
* **Action routing:** Most endpoints serve multiple actions via `?action=<name>` in the query string

OpenAI Spec: <https://openapi.gitbook.com/o/VeXVmIueGvLpVdXaTsb8/spec/indexify-0-1-8.json>

### Error Format

All errors return a JSON object with an `error` field:

```json
{
  "error": "Description of the error"
}
```

Common HTTP status codes: `400` (bad request), `401` (unauthorized), `403` (forbidden), `404` (not found), `500` (server error).

***

### Endpoints

#### Account

Manage user profiles, social links, notifications, and notification preferences.

| Method | Endpoint                            | Action              | Auth     | Description                                                   |
| ------ | ----------------------------------- | ------------------- | -------- | ------------------------------------------------------------- |
| POST   | `/api/user_info.php`                | `fetch`             | Required | Get authenticated user's full profile                         |
| POST   | `/api/user_info.php`                | `update`            | Required | Update profile fields (username, bio, slippage, priority fee) |
| POST   | `/api/user_info.php`                | `check_name`        | None     | Check if a username is available                              |
| POST   | `/api/user_info.php`                | `search`            | None     | Search users by username or bio                               |
| POST   | `/api/user_info.php`                | `delete_account`    | Required | Permanently delete account (requires 2FA)                     |
| POST   | `/api/profile.php`                  | `twitter`           | Required | Set or remove Twitter handle                                  |
| POST   | `/api/profile.php`                  | `telegram`          | Required | Set or remove Telegram handle                                 |
| POST   | `/api/profile.php`                  | `discord`           | Required | Set or remove Discord username                                |
| POST   | `/api/profile.php`                  | `linkedin`          | Required | Set or remove LinkedIn URL                                    |
| POST   | `/api/profile.php`                  | `personal`          | Required | Set or remove personal website URL                            |
| POST   | `/api/notifications.php`            | `get_notifications` | Required | Get paginated notifications                                   |
| POST   | `/api/notifications.php`            | `get_unread_count`  | Required | Get unread notification count                                 |
| POST   | `/api/notifications.php`            | `mark_read`         | Required | Mark a notification as read                                   |
| POST   | `/api/notifications.php`            | `dismiss_all`       | Required | Dismiss all notifications                                     |
| POST   | `/api/notifications.php`            | `delete`            | Required | Delete a single notification                                  |
| POST   | `/api/notifications.php`            | `delete_all`        | Required | Delete all notifications                                      |
| POST   | `/api/notification_preferences.php` | `get`               | Required | Get notification preferences                                  |
| POST   | `/api/notification_preferences.php` | `update`            | Required | Update a single preference                                    |
| POST   | `/api/notification_preferences.php` | `update_bulk`       | Required | Update multiple preferences at once                           |

***

#### Stacks

Discover, create, manage, and query holdings for stacks (curated token portfolios).

| Method | Endpoint              | Action                 | Auth     | Description                                         |
| ------ | --------------------- | ---------------------- | -------- | --------------------------------------------------- |
| POST   | `/api/stack_info.php` | `paginated_list`       | Optional | Browse stacks with filters, sorting, and pagination |
| POST   | `/api/stack_info.php` | `trending`             | Optional | Get trending stacks (capped at 50)                  |
| POST   | `/api/stack_info.php` | `official`             | Optional | Get official Indexify stacks                        |
| POST   | `/api/stack_info.php` | `related_stacks`       | Optional | Find stacks containing a specific token             |
| POST   | `/api/stack_info.php` | `fetch`                | Optional | Fetch stacks by IDs, slugs, or creator              |
| POST   | `/api/stack_info.php` | `my_stacks`            | Required | Get the authenticated user's created stacks         |
| POST   | `/api/stack_info.php` | `create`               | Required | Create a new stack                                  |
| POST   | `/api/stack_info.php` | `update`               | Required | Update stack name, description, or category         |
| POST   | `/api/stack_info.php` | `close`                | Required | Permanently close a stack                           |
| POST   | `/api/stack_info.php` | `check_name`           | None     | Validate a proposed stack name                      |
| POST   | `/api/stack_info.php` | `check_description`    | None     | Validate a proposed stack description               |
| POST   | `/api/stack_info.php` | `user_stack_holdings`  | Required | Get your holdings and P\&L for a stack              |
| POST   | `/api/stack_info.php` | `get_creator_holdings` | None     | Get the creator's holdings (if public)              |
| POST   | `/api/stack_info.php` | `investors`            | None     | Get investor count for a stack                      |
| POST   | `/api/stack_info.php` | `followers`            | None     | Get follower count for a stack                      |

***

#### Stack Chat

Community messages and creator notes on stack pages.

| Method | Endpoint        | Action       | Auth     | Description                                |
| ------ | --------------- | ------------ | -------- | ------------------------------------------ |
| POST   | `/api/chat.php` | `addMessage` | Required | Post a message or creator note             |
| POST   | `/api/chat.php` | `getAll`     | Optional | Get paginated chat messages                |
| POST   | `/api/chat.php` | `togglePin`  | Required | Pin or unpin a creator note (creator only) |

***

#### Stack Wars

Time-bound competitions between stacks with AI-generated battle reports.

| Method | Endpoint              | Action   | Auth     | Description                               |
| ------ | --------------------- | -------- | -------- | ----------------------------------------- |
| POST   | `/api/stack_wars.php` | `list`   | Optional | List all stack wars                       |
| POST   | `/api/stack_wars.php` | `detail` | Optional | Get full details and AI summary for a war |

***

#### Tokens

Search, list, and get details on tokens. Follow tokens to track them.

| Method | Endpoint                 | Action              | Auth     | Description                            |
| ------ | ------------------------ | ------------------- | -------- | -------------------------------------- |
| POST   | `/api/token_info.php`    | `search`            | None     | Search tokens by name or symbol        |
| POST   | `/api/token_info.php`    | `new`               | Required | Add a new token by mint address        |
| POST   | `/api/token_info.php`    | `detail`            | Optional | Get full token details and stats       |
| POST   | `/api/token_info.php`    | `list`              | Optional | List tokens with filters and sorting   |
| POST   | `/api/token_info.php`    | `paginated_list`    | Optional | List tokens with pagination metadata   |
| POST   | `/api/token_info.php`    | `fetch`             | Optional | Alias for list                         |
| POST   | `/api/token_info.php`    | `categories`        | None     | Get all token categories               |
| POST   | `/api/token_info.php`    | `follow`            | Required | Follow or unfollow a token (toggle)    |
| POST   | `/api/token_info.php`    | `followers`         | Optional | Get follower count for a token         |
| POST   | `/api/token_trading.php` | `get_trading_info`  | Optional | Get trading readiness info for a token |
| POST   | `/api/token_trading.php` | `get_company_stats` | None     | Get aggregate company stack count      |

***

#### Trading

Execute swaps, check balances, manage orders, and view transaction history.

| Method | Endpoint                        | Action            | Auth     | Description                                                     |
| ------ | ------------------------------- | ----------------- | -------- | --------------------------------------------------------------- |
| POST   | `/api/txn.php`                  | `swap`            | Required | Buy or sell a stack                                             |
| POST   | `/api/txn.php`                  | `balance`         | Required | Get all token balances                                          |
| POST   | `/api/txn.php`                  | `usdc_balance`    | Required | Get USDC balance                                                |
| POST   | `/api/txn.php`                  | `total_balance`   | Required | Get total portfolio value in USDC                               |
| POST   | `/api/txn.php`                  | `address`         | Required | Get wallet public key                                           |
| POST   | `/api/txn.php`                  | `withdraw_usdc`   | Required | Withdraw USDC to an external wallet (requires SMS verification) |
| POST   | `/api/txn.php`                  | `export_key`      | Required | Export wallet private key (requires SMS verification)           |
| POST   | `/api/orders.php`               | `details`         | Required | Get order details and transactions                              |
| POST   | `/api/orders.php`               | `status`          | Required | Get order status                                                |
| POST   | `/api/orders.php`               | `partial_details` | Required | Get partial order breakdown                                     |
| POST   | `/api/orders.php`               | `acknowledge`     | Required | Acknowledge a partial order                                     |
| POST   | `/api/orders.php`               | `retry`           | Required | Retry failed tokens in a partial order                          |
| POST   | `/api/orders.php`               | `sell_all`        | Required | Sell all tokens from a partial order                            |
| POST   | `/api/orders.php`               | `retry_chain`     | Required | Get full retry history for an order                             |
| POST   | `/api/user_orders.php`          | —                 | Required | List all orders for the authenticated user                      |
| POST   | `/api/stack_partial_orders.php` | —                 | Required | List outstanding partial orders for a stack                     |
| GET    | `/api/transaction_history.php`  | `list`            | Required | Get paginated transaction history                               |
| GET    | `/api/transaction_history.php`  | `detail`          | Required | Get a single transaction with token breakdown                   |
| GET    | `/api/transaction_history.php`  | `summary`         | Required | Get transaction summary counts                                  |

***

#### Fees

Calculate trading fees and retrieve fee bounds. No authentication required.

| Method | Endpoint       | Action               | Auth | Description                                 |
| ------ | -------------- | -------------------- | ---- | ------------------------------------------- |
| POST   | `/api/fee.php` | `calculate`          | None | Calculate fees for a given amount and stack |
| POST   | `/api/fee.php` | `min_buy`            | None | Get the minimum buy amount                  |
| POST   | `/api/fee.php` | `creator_fee_bounds` | None | Get min, max, and default creator fee       |

***

#### Social

Follow stacks and users, view leaderboards, public profiles, and referrals.

| Method | Endpoint                | Action                   | Auth     | Description                                     |
| ------ | ----------------------- | ------------------------ | -------- | ----------------------------------------------- |
| POST   | `/api/subscription.php` | `followers`              | Required | Get stack follower count and follow status      |
| POST   | `/api/subscription.php` | `follow`                 | Required | Follow a stack                                  |
| POST   | `/api/subscription.php` | `unfollow`               | Required | Unfollow a stack                                |
| POST   | `/api/subscription.php` | `follow_user`            | Required | Follow a user                                   |
| POST   | `/api/subscription.php` | `unfollow_user`          | Required | Unfollow a user                                 |
| POST   | `/api/subscription.php` | `user_followers`         | Optional | Get a user's followers                          |
| POST   | `/api/subscription.php` | `user_following`         | None     | Get who a user follows                          |
| POST   | `/api/subscription.php` | `user_follow_status`     | Required | Check mutual follow status                      |
| GET    | `/api/user_info.php`    | `leaderboard`            | Optional | Get the creator leaderboard                     |
| POST   | `/api/user_info.php`    | `top_creators`           | Optional | Get top 5 creators                              |
| POST   | `/api/user_info.php`    | `public_profile`         | None     | Get a user's public profile                     |
| POST   | `/api/user_info.php`    | `public_profile_metrics` | None     | Get a user's performance metrics                |
| POST   | `/api/refer.php`        | —                        | Required | Generate a referral link                        |
| GET    | `/api/referrals.php`    | —                        | Required | Get multi-level referral data with volume stats |

***

#### Market Data

Bulk price and stats lookups. No authentication required.

| Method | Endpoint                    | Action | Auth | Description                                        |
| ------ | --------------------------- | ------ | ---- | -------------------------------------------------- |
| POST   | `/api/bulk_stack_stats.php` | —      | None | Get prices and change stats for up to 1,000 stacks |
| POST   | `/api/bulk_token_stats.php` | —      | None | Get prices and change stats for up to 1,000 tokens |

***

#### Search

Unified search across stacks, creators, and tokens. No authentication required.

| Method | Endpoint          | Action | Auth | Description                                                              |
| ------ | ----------------- | ------ | ---- | ------------------------------------------------------------------------ |
| POST   | `/api/search.php` | —      | None | Simple search (stack names) or faceted search (stacks, creators, tokens) |

***

### Rate Limits

To ensure platform stability and protect against automated abuse, the Indexify API enforces rate limits on all endpoints. These limits are applied per client IP address.

* **Base Rate:** 10 requests per second
* **Burst Capacity:** 100 requests
* **Algorithm:** Leaky Bucket (Queue-based)

#### How It Works: The "Leaky Bucket"

Indexify uses a queue-based system to handle traffic. This allows your application to send a sudden burst of requests without being immediately blocked, but it enforces a steady processing speed.

1. **Immediate Processing:** Your first request is processed instantly.
2. **Queueing (Burst):** If you send a spike of up to 100 requests simultaneously (e.g., during a page load), the server will accept them all into a queue.
3. **Smoothing:** The server "leaks" requests out of that queue at a steady rate.

> **The Result:** If you fire 50 requests at once, the 1st request is handled immediately, but the 50th request will experience a \~4.9-second delay (Time to First Byte) while it waits its turn in the queue.

#### Rate Limit Errors

If you exceed your Burst Capacity (more than 100 requests waiting in the queue), the server will stop queueing and immediately return an error:

**HTTP 503 Service Unavailable** (or **429 Too Many Requests**)

#### Best Practices for Developers

* **Throttle Locally:** If your application needs to make dozens of requests, space them out \~100ms on the client side to avoid the server-side queue delay.
* **Handle Retries:** Implement an exponential backoff strategy if you receive a `503` or `429` status code.