# Getting started

## 1. Make a free call

The company directory needs no key and no payment. It lists the companies we hold financial statements for.

```bash
curl "https://iposignal.xyz/api/agent/companies?q=circle"
```

```json
{
  "version": "1",
  "count": 1,
  "total": 1,
  "offset": 0,
  "limit": 200,
  "nextOffset": null,
  "data": [
    {
      "symbol": "CRCL",
      "company": "Circle Internet Group, Inc.",
      "cik": "0001876042",
      "latestPeriodEnd": "2026-09-30",
      "preIpoCount": 4,
      "postIpoCount": 8
    }
  ]
}
```

## 2. Create an API key

Sign in at [iposignal.xyz/account](https://iposignal.xyz/account) and create a key under **API access**. Any account can; there is nothing to pay.

- The key starts with `ips_live_` and is shown once. Only its hash is stored, so it cannot be shown again: copy it when you create it.
- A free account includes 250 calls a month, and a subscription 10,000.
- You can hold up to 5 active keys and revoke any of them from the same page.

Keep the key in an environment variable rather than in code:

```bash
export IPOSIGNAL_API_KEY="ips_live_YOUR_KEY"
```

## 3. Call a paid endpoint

```bash
curl -i -H "Authorization: Bearer $IPOSIGNAL_API_KEY" \
  "https://iposignal.xyz/api/agent/ipo-events?types=lockup_expiry"
```

A paid endpoint wraps its payload as `{ "version": "1", "data": ... }`. The response header `X-API-Quota-Remaining` says how many calls are left this month.

Only a delivered result counts against the quota. Asking for a ticker we do not cover returns `404` and costs nothing.

## 4. Connect an MCP client

An MCP client needs no key: it opens a browser and you sign in. In Claude Code:

```bash
claude mcp add --transport http iposignal https://iposignal.xyz/api/oauth/mcp
```

Then run `/mcp` in Claude Code and authenticate. Other clients, and connecting with a key instead, are covered in [MCP server](https://iposignal.xyz/docs/mcp.md).

## Next

- [API reference](https://iposignal.xyz/docs/api-reference.md): every endpoint, its parameters and an example response.
- [Authentication](https://iposignal.xyz/docs/authentication.md): keys and x402 in detail.
- [Quotas and errors](https://iposignal.xyz/docs/errors.md): what each status code means and whether to retry.