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

# Agent Skill

> Install skill.md into Claude, Cursor, Codex, or any AI coding tool so it knows how to use the AlphaInsider API correctly.

# Using the AlphaInsider Skill

`skill.md` is a single markdown file that teaches AI coding assistants how to use the AlphaInsider API — including the display rules, order decision matrix, WebSocket channels, and auth flow. Install it once, reference it in prompts.

The canonical, always-up-to-date copy lives at **[https://api.alphainsider.com/skill.md](https://api.alphainsider.com/skill.md)**.

## 1. Install the skill

Install via the `skills` CLI — it detects which AI tools you have installed and drops `skill.md` into the correct folder for each (Claude, Cursor, Codex, and more). Works the same on macOS, Linux, and Windows.

```bash theme={null}
npx skills add https://api.alphainsider.com
```

No flags, no paths, no shell-specific commands — `npx` runs the CLI without a global install. Requires [Node.js](https://nodejs.org) 18+.

## 2. Set your API key (and optional scoping IDs)

Generate a JWT at [alphainsider.com/settings/developers](https://alphainsider.com/settings/developers) with the scopes you need (e.g. `newOrder`, `getUserInfo`).

Put it in a `.env` file in the directory your agent runs from:

```env theme={null}
ALPHAINSIDER_API_KEY=<your_jwt>

# Optional — pins the agent to a specific strategy / bot
ALPHAINSIDER_STRATEGY_ID=<strategy_id>
ALPHAINSIDER_BOT_ID=<bot_id>
```

Or export in your shell:

```bash theme={null}
export ALPHAINSIDER_API_KEY="<your_jwt>"
export ALPHAINSIDER_STRATEGY_ID="<strategy_id>"   # optional
export ALPHAINSIDER_BOT_ID="<bot_id>"             # optional
```

**When the optional IDs are set, the agent MUST use them by default for every trade / bot call and will not ask which strategy or bot to touch.** When they are **not** set and a call needs one, the skill tells the agent to ask you first — it will not guess or pick the first strategy from your account. Set both if you run multiple strategies or bots and want to avoid trade-on-wrong-account mistakes.

The skill loads all env vars via `dotenv` / `os.getenv` / `process.env` — never hardcode them.

## 3. Reference it in prompts

Most tools auto-discover a skill once it's in the right folder. When in doubt, mention it explicitly.

| Tool            | How to use it                                                                                                            |
| --------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Claude**      | Auto-indexed from project root or `~/.claude/skills/`. Or `@skill.md`.                                                   |
| **Cursor**      | Auto-indexed from project root or `~/.cursor/skills/`. Or `@skill.md`.                                                   |
| **Codex**       | Auto-indexed from project root or `~/.codex/skills/`. Or `@skill.md`.                                                    |
| **Generic CLI** | Keep `skill.md` in the working dir and reference it: `codex "using skill.md, ..."`. Or pipe it: `cat skill.md \| <cli>`. |

Example prompts:

```
/alphainsider place a newOrderAllocations rebalance to 80% SPY for strategy YbKCgktxu0ugmQ1QKCfA3 and print the resulting portfolio value in USD.
```

```
Using the alphainsider skill, write a function that takes a strategy_id and prints portfolio value — USD if input_multiplier is set, percent otherwise.
```

```
/alphainsider print my strategy's information, positions, and max buying power.
```

## 4. Keep it fresh

Update the skill any time to pull new endpoints and updated rules — it overwrites the existing `skill.md`:

```bash theme={null}
npx skills update
```

## Troubleshooting

* **Agent ignores the skill** — reference it explicitly in the prompt ("follow the rules in skill.md") and make sure the file is in the project root or the tool's skills folder.
* **Numbers look wrong (e.g. `1.05` instead of `$105,000`)** — the agent didn't apply the Display Rule. Remind it: "use `input_multiplier` from `getStrategySubscriptions` for USD, or percent fallback if null — never raw `strategy_value`".
* **Auth errors** — check `echo $ALPHAINSIDER_API_KEY | cut -c1-20`. Then `POST /verifyToken` with the token.
* **429 rate limit** — see the Limits table in skill.md §9 and back off.

## Where to go next

* Full interactive docs & OpenAPI explorer: [api.alphainsider.com](https://api.alphainsider.com)
* Trading examples (deep dive): [trading-examples](/resources/examples/trading-examples)
* WebSocket channels: [websockets](/resources/websockets)
* Account limits: [limits](/resources/limits)