---
name: iposignal-api
description: Use when a task needs US IPO data - deal terms, pricing, lock-up and quiet-period expiries, first-day returns, pre- and post-IPO financial statements from SEC filings, valuation multiples for any US-listed company, or IPO market sentiment. Covers the IPOSignal HTTP API and MCP server.
---

# IPOSignal API

## Basics

- Base URL: `https://iposignal.xyz`. Every endpoint is a `GET` returning JSON.
- Paid endpoints take `Authorization: Bearer <key>`. Read the key from the `IPOSIGNAL_API_KEY` environment variable; never hard-code it.
- A key is free: the user creates one at https://iposignal.xyz/account. It includes 250 calls a month, 10,000 with a subscription.
- Without a key, a paid endpoint answers `402` with x402 payment terms (USDC on Base). Pay only if you hold a wallet and the user allows spending.
- Only a `200` is charged or counted. `404`, `400` and `500` are free.
- Paid endpoints wrap the payload as `{ "version": "1", "data": ... }`. The free company directory returns its fields at the top level.

## Identify the company

- Start from a ticker when you have one. Tickers are case-insensitive.
- A ticker is not a stable identifier: symbols get reassigned between registrants. When the requested symbol now belongs to a different company than the record served, the response carries a `symbolNote`. Read it before using the figures.
- The SEC CIK is stable. Responses return it as `cik`, 10 digits with leading zeros.
- To check coverage before paying, call the free `/api/agent/companies?q=<ticker or name>`.

## Endpoint map

| Need | Call | Price |
| --- | --- | --- |
| Companies with financial statements | `/api/agent/companies?q=circle` | Free |
| IPO snapshot by ticker | `/api/agent/ipo/by-symbol/{symbol}` | $0.01 |
| IPO snapshot by id | `/api/agent/ipo/{id}` | $0.01 |
| Financial statements | `/api/agent/financials/by-symbol/{symbol}` | $0.01 |
| Live valuation metrics | `/api/agent/company-metrics?symbol=CRCL` | $0.02 |
| IPO market sentiment | `/api/agent/ipo-sentiment?days=30` | $0.01 |
| Social sentiment for one IPO | `/api/agent/social-sentiment?symbol=CRCL` | $0.01 |
| IPO events calendar | `/api/agent/ipo-events?types=lockup_expiry` | $0.02 |

Parameters and response shapes: https://iposignal.xyz/docs/api-reference.md or https://iposignal.xyz/openapi.json.

## Reading the data correctly

- Offer terms are final only when they come from a final prospectus (424B). A registration statement (S-1, F-1) is filed before pricing and leaves the price blank. Check `offering.termsAreFinal` before quoting a price as final.
- `marketCap` and `offerSize` are different quantities. `marketCap` is shares outstanding after the offering times the offer price; `offerSize` is the gross proceeds raised.
- Financial statements are split into periods before and after the IPO. Interim periods carry annualised figures beside the reported ones; do not compare an annualised figure with a reported one.
- Social sentiment is read once, before listing. `ageDays` says how old the reading is and `reliable` is false when too few posts back it.
- A field is `null` or absent when the filing does not state it. Do not fill the gap with an estimate.

## Dates

- Dates are `YYYY-MM-DD`. Timestamps are ISO 8601 in UTC.
- `/api/agent/ipo-events` takes `from` and `to` (at most 366 days apart; default today to today + 30 days) and `types`, a comma-separated subset of `lockup_expiry`, `quiet_period_expiry`, `listing`.

## Errors

- `400`: fix the parameter named in `error`.
- `401`: the key is wrong or revoked. Ask the user for a new one.
- `402`: no key, or the monthly quota is spent (`error` says which). Do not loop on it.
- `404`: not covered, or not computed yet. Do not retry.
- `500`, `503`: retry after a pause.

## MCP

For chat-style research, use the MCP server (streamable HTTP). `https://iposignal.xyz/api/oauth/mcp` signs the user in over OAuth, or takes the same key as a bearer header; `https://iposignal.xyz/api/mcp` needs no credential and charges premium tools over x402. Tools: `get_ipo_overview` (free), `lookup_companies_with_financials` (free), `get_ipo_snapshot`, `get_ipo_sentiment`, `get_company_metrics`, `get_company_financials`, `get_ipo_social_sentiment`, `get_ipo_pipeline` (free), `get_ipo_filings` (free), `get_ipo_events`.

## Read more

- Docs: https://iposignal.xyz/docs (add `.md` to any page), all in one file at https://iposignal.xyz/llms-full.txt
- OpenAPI: https://iposignal.xyz/openapi.json