# FomoData

> FomoData is a developer API for authorized Fomo data: public profiles, Trade Theses, token activity and thesis velocity, search, signed webhooks and realtime streams (WebSocket and SSE), behind one versioned REST API and a TypeScript SDK. FomoData is independent and is not affiliated with, endorsed by, or sponsored by FOMO Labs Inc.

## Essentials

- Base URL: https://fomodata.dev/v1
- Auth: send `Authorization: Bearer <key>` on every request. Never put keys in URLs or browser bundles.
- Keys: `fd_test_…` keys work right after sign-up and return clearly labelled sandbox data (`livemode: false`, `source: "sandbox"`, handles start with `@sbx_`). `fd_live_…` keys return real data and are limited to approved projects.
- Get a key: sign up at https://fomodata.dev/signup, then open https://fomodata.dev/dashboard → API keys.
- Format: JSON. Lists are `{ object: "list", data, next_cursor, has_more }`; pass `cursor` (and `limit`) for the next page.
- Errors: `{ error: { type, code, message, request_id, doc_url? } }`. Quote `request_id` (also the `X-FomoData-Request-Id` header) to support.
- Rate limits: every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (unix seconds). `429 RATE_LIMITED` comes with `Retry-After`; `QUOTA_EXCEEDED` means the monthly plan quota is used up (do not retry).
- OpenAPI 3.1: https://fomodata.dev/openapi.json
- Discovery: `GET https://fomodata.dev/v1` returns these links plus `stream`, the current WebSocket URL (null while unavailable; use SSE at `https://fomodata.dev/v1/events/stream` then).

## Quickstart

```bash
curl https://fomodata.dev/v1/me -H "Authorization: Bearer $FOMODATA_API_KEY"
curl 'https://fomodata.dev/v1/theses?token=$RUN&since=1h' -H "Authorization: Bearer $FOMODATA_API_KEY"
```

```ts
// npm install https://fomodata.dev/sdk/fomodata-sdk-0.1.0.tgz
import { FomoData } from "@fomodata/sdk";

const fomo = new FomoData({ apiKey: process.env.FOMODATA_API_KEY });
const profile = await fomo.profiles.get("@sbx_milo");
const theses = await fomo.theses.list({ token: "$RUN", since: "1h" });
const check = await fomo.theses.verify({ handle: "@sbx_milo", token: "$RUN", after: start, before: end }); // { verified, thesis_id | reason }
fomo.streams.subscribe({ event: "thesis.created", token: "$RUN", onEvent: (e) => console.log(e.data) });
```

The SDK defaults to this base URL; pass `baseUrl` (or set `FOMODATA_API_BASE_URL`) only for a self-hosted API.

## Endpoints (25)

### Meta

- `GET /v1/me`: Inspect the current API key. Scope: any key. Reference: https://fomodata.dev/docs/api/get-me

### Profiles

- `GET /v1/profiles`: Look up a profile. Scope: profiles:read. Query: id, handle, fomo_user_id. Reference: https://fomodata.dev/docs/api/get-profiles
- `GET /v1/profiles/{ref}`: Retrieve a profile. Scope: profiles:read. Reference: https://fomodata.dev/docs/api/get-profiles-ref

### Theses

- `GET /v1/theses`: List theses. Scope: theses:read. Query: profile, handle, token, chain, created_after, created_before, since, sort, limit, cursor. Reference: https://fomodata.dev/docs/api/get-theses
- `GET /v1/theses/{id}`: Retrieve a thesis. Scope: theses:read. Reference: https://fomodata.dev/docs/api/get-theses-id
- `POST /v1/verify/thesis`: Verify a thesis. Scope: theses:read. JSON body. Reference: https://fomodata.dev/docs/api/post-verify-thesis

### Tokens

- `GET /v1/tokens/{ref}`: Retrieve a token. Scope: tokens:read. Query: chain. Reference: https://fomodata.dev/docs/api/get-tokens-ref
- `GET /v1/tokens/{ref}/activity`: Token activity. Scope: tokens:read. Query: chain, recent. Reference: https://fomodata.dev/docs/api/get-tokens-ref-activity
- `GET /v1/tokens/{ref}/thesis-velocity`: Token thesis velocity. Scope: tokens:read. Query: chain. Reference: https://fomodata.dev/docs/api/get-tokens-ref-thesis-velocity

### Search

- `GET /v1/search`: Search. Scope: search:read. Query: q (required), types, limit. Reference: https://fomodata.dev/docs/api/get-search
- `POST /v1/search/semantic`: Semantic search (coming soon). Scope: search:read. JSON body. COMING SOON (answers 404 FEATURE_DISABLED today). Reference: https://fomodata.dev/docs/api/post-search-semantic

### Events

- `GET /v1/events`: List events. Scope: events:read. Query: types, limit, cursor. Reference: https://fomodata.dev/docs/api/get-events
- `GET /v1/events/{id}`: Retrieve an event. Scope: events:read. Reference: https://fomodata.dev/docs/api/get-events-id

### Streams

- `GET /v1/events/stream`: Stream events (Server-Sent Events). Scope: streams:read. Query: types, token, handle, chain, from_cursor. Reference: https://fomodata.dev/docs/api/get-events-stream

### Webhooks

- `POST /v1/webhook-deliveries/{id}/replay`: Replay a delivery. Scope: webhooks:write. Reference: https://fomodata.dev/docs/api/post-webhook-deliveries-id-replay
- `GET /v1/webhooks`: List webhook endpoints. Scope: webhooks:write. Query: limit, cursor. Reference: https://fomodata.dev/docs/api/get-webhooks
- `POST /v1/webhooks`: Create a webhook endpoint. Scope: webhooks:write. JSON body. Reference: https://fomodata.dev/docs/api/post-webhooks
- `GET /v1/webhooks/{id}`: Retrieve a webhook endpoint. Scope: webhooks:write. Reference: https://fomodata.dev/docs/api/get-webhooks-id
- `PATCH /v1/webhooks/{id}`: Update a webhook endpoint. Scope: webhooks:write. JSON body. Reference: https://fomodata.dev/docs/api/patch-webhooks-id
- `DELETE /v1/webhooks/{id}`: Delete a webhook endpoint. Scope: webhooks:write. Reference: https://fomodata.dev/docs/api/delete-webhooks-id
- `GET /v1/webhooks/{id}/deliveries`: List deliveries for a webhook. Scope: webhooks:write. Query: limit, cursor, status. Reference: https://fomodata.dev/docs/api/get-webhooks-id-deliveries
- `POST /v1/webhooks/{id}/rotate-secret`: Rotate the signing secret. Scope: webhooks:write. Reference: https://fomodata.dev/docs/api/post-webhooks-id-rotate-secret
- `POST /v1/webhooks/{id}/test`: Send a test event. Scope: webhooks:write. Reference: https://fomodata.dev/docs/api/post-webhooks-id-test

### Testing

- `POST /v1/test/theses`: Create a test thesis. Scope: theses:read. JSON body. Reference: https://fomodata.dev/docs/api/post-test-theses

### Wallets

- `GET /v1/wallets/{ref}`: Public wallet associations. Scope: wallets:read. COMING SOON (answers 404 FEATURE_DISABLED today). Reference: https://fomodata.dev/docs/api/get-wallets-ref

The realtime WebSocket is not an HTTP operation: connect to the `stream` URL from discovery, send `{"action":"auth","api_key":"…"}` as the first message, then subscribe. The SDK handles auth, heartbeats, reconnects and cursor resume.

## Scopes

- `profiles:read`: Resolve Fomo profiles by handle or id.
- `theses:read`: List, read and verify Trade Theses.
- `tokens:read`: Token metadata, activity and thesis velocity.
- `search:read`: Search theses, profiles and tokens.
- `events:read`: List and fetch historical events.
- `streams:read`: Consume realtime events over WebSocket / SSE.
- `webhooks:write`: Create and manage webhook endpoints.

## Webhooks

- Create endpoints with `POST /v1/webhooks` (scope `webhooks:write`); the signing secret (`whsec_…`) is returned once.
- Every delivery is signed: `FomoData-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>`, tolerance 300 s. Deduplicate on `FomoData-Event-Id`; retries and replays reuse it.
- Non-2xx responses are retried after 1 min, 5 min, 30 min, 2 h and 12 h; `410 Gone` is not retried.

## Docs

- [API overview](https://fomodata.dev/api): base URL, auth, endpoints at a glance
- [Quickstart](https://fomodata.dev/docs/quickstart): first call in three steps
- [API reference](https://fomodata.dev/docs/api): every endpoint with parameters, schemas, errors and samples
- [Authentication](https://fomodata.dev/docs/authentication): keys, scopes, environments
- [Errors](https://fomodata.dev/docs/errors): every error code
- [Rate limits](https://fomodata.dev/docs/rate-limits): limits per plan and endpoint class
- [Webhooks](https://fomodata.dev/docs/webhooks): events, signatures, retries
- [Streams](https://fomodata.dev/docs/streams): WebSocket and SSE protocol
- [TypeScript SDK](https://fomodata.dev/docs/sdk): `npm install https://fomodata.dev/sdk/fomodata-sdk-0.1.0.tgz`
- [Playground](https://fomodata.dev/docs/playground): try requests with a test key
- [Status](https://fomodata.dev/status)