DEVELOPER DOCUMENTATION / V1

Your first request

Sign in to Tidelight, choose a workspace, create a developer project, and issue a key. Its secret is shown once. Store it on your server and call the versioned endpoint.

Organizations and roles

Your account starts with a private personal workspace. You can create organizations, group projects, and add people who already have a Tidelight account. Invitation emails are not enabled yet. Owners manage administrators; owners and administrators manage members; developers can create projects and credentials; readers can review activity. Removing a member or changing them to reader revokes credentials they issued in that organization. Job and usage views are shared with organization members.

curl 'https://api.tidelight.app/v1/market/instruments?kind=rtoken&limit=20' \
  -H 'Authorization: Bearer YOUR_TIDELIGHT_KEY'

Authentication

Send the secret as a Bearer token over HTTPS. Keys are hashed at rest, scoped to the permissions selected at creation (market:read, research:run, and/or alerts:manage), and expire on the date selected at creation. Production and test keys currently access the same live read only market source; the environment label helps you separate applications. Keys can be rotated in the console; rotation immediately revokes the old secret and preserves its scopes, quotas, and expiry. The replacement secret is shown once. Revocation takes effect on the next request. The Security log records key creation, rotation, and revocation with actor and project details, and can be filtered by event type.

List tokenized equity instruments

GET /api/v1/market/instruments

Returns data, next_cursor, generated_at, and request_id. Instrument rows include symbol, type, underlying ticker, issuer name, quote currency, last price, 24 hour change, provider timestamp, market session status, and source. Prices are Bitget tokenized equity spot prices; they are not direct US stock quotes.

Asynchronous company research

Keys need the research:run scope. This job creates a company snapshot from the existing Tidelight market adapter and headline discovery sources. It reports provider provenance and limitations; it is not a valuation, forecast, recommendation, or order instruction.

curl -X POST 'https://api.tidelight.app/v1/research/jobs'   -H 'Authorization: Bearer YOUR_TIDELIGHT_KEY'   -H 'Idempotency-Key: nvda-$(date +%s)'   -H 'Content-Type: application/json'   -d '{"ticker":"NVDA"}'

A successful new request returns 202 and a job_id. Poll GET /api/v1/research/jobs/{job_id} for status and result. Send DELETE to request cancellation. Each project may start 10 jobs per rolling hour; the API enforces each key’s request quotas too. The console’s Research jobs page lists actual jobs across organizations you belong to.

Errors and limits

Errors use { error: { code, message, request_id } }. A missing or revoked key returns 401; missing scope returns 403; invalid parameters return 400; quota exhaustion returns 429; unavailable upstream data returns 503. Each key starts with 30 requests per rolling minute and 10,000 per calendar month. Requests that pass credential validation count toward usage even if the provider fails.

API explorer

In the console, select an active project credential and run the instrument request. The explorer applies that key’s scope and quota, records a real request, and shows the response, request ID, time, and copyable code. Its server retrieves only the stored key hash after verifying your signed in account; the secret is never sent back to the browser.

Webhook delivery

Project webhooks emit research.job.completed and research.job.failed. Configure destinations in the developer console. Destinations must use public HTTPS on port 443; private, local, reserved, redirecting, and query-string destinations are rejected. Signing secrets are shown once and encrypted at rest. Rotate a secret if it is lost or exposed.

Use an alerts:manage scoped key with GET or POST /api/v1/webhooks to list or create project endpoints. Use PATCH or DELETE /api/v1/webhooks/<endpoint_id> to update, rotate, or disable an endpoint, and GET /api/v1/webhooks/deliveries to read the latest 100 delivery records. The authenticated console offers the same controls.

curl -X POST 'https://api.tidelight.app/v1/webhooks'   -H "Authorization: Bearer $TIDELIGHT_API_KEY"   -H 'Content-Type: application/json'   -d '{"name":"Research events","url":"https://hooks.example.com/tidelight","events":["research.job.completed","research.job.failed"]}'

Each POST includes Tidelight-Event-Id, Tidelight-Event, and Tidelight-Signature headers. The signature format is t=<unix-seconds>,v1=<hex-hmac>; verify HMAC-SHA256 over <timestamp>.<raw request body> and reject timestamps outside your replay window. Deduplicate by event ID because delivery is at least once. HTTP 2xx acknowledges delivery. Network errors, 408, 429, and 5xx responses retry with bounded backoff for up to eight attempts; the delivery worker polls once per minute. Terminal delivery history is retained for 90 days; other 4xx responses are recorded as failed. Delivery history includes status, response code, duration, and attempt records, but never stores response bodies.

{
  "id": "<event UUID>",
  "type": "research.job.completed",
  "created_at": "<ISO timestamp>",
  "data": { "job_id": "<job UUID>", "ticker": "NVDA", "status": "complete", "completed_at": "<ISO timestamp>", "error_code": null }
}

Connect with the MCP server

Tidelight exposes a stateless Streamable HTTP MCP endpoint at https://mcp.tidelight.app/mcp. Send an active API key in the Authorization: Bearer … header, or connect through OAuth 2.1 authorization code with PKCE. OAuth consent is tied to one of your existing developer keys and cannot exceed its selected scopes, expiry, quota, or revocation state. Tokens are audience-bound to this MCP resource; they do not authenticate direct REST requests. A market:read grant can discover tokenized equity tools; a research:run grant can start, inspect, and cancel research jobs. Tool calls use the same server side authorization, quotas, and usage accounting as the REST API. Initialize and tool discovery do not create usage records.

The endpoint is stateless and returns JSON responses. Use an MCP client that supports Streamable HTTP and custom Bearer authorization headers. Client interoperability is verified with the official TypeScript SDK; no named third party client is certified yet.

curl -X POST 'https://mcp.tidelight.app/mcp'   -H "Authorization: Bearer $TIDELIGHT_API_KEY"   -H 'Content-Type: application/json'   -H 'Accept: application/json, text/event-stream'   -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"tidelight-client","version":"1.0.0"}}}'

Available tools are tidelight_search_tokenized_equities, tidelight_get_tokenized_equity, tidelight_start_company_research, tidelight_get_research_job, and tidelight_cancel_research_job. Only tools permitted by the selected credential and OAuth grant scopes are listed. Research returns structured snapshots and understandable status; private model reasoning is not exposed. OAuth authorization uses dynamic public client registration, S256 PKCE, explicit signed-in consent, short-lived access tokens, rotating refresh tokens, resource-bound audience checks, and revocation in the developer console. Authorization Server Metadata: https://tidelight.app/.well-known/oauth-authorization-server; Protected Resource Metadata: https://mcp.tidelight.app/.well-known/oauth-protected-resource/mcp. Prompts, additional MCP resources, and live trading tools are not enabled.

SDKs

TypeScript and Python clients are available in the Tidelight repository under sdk/typescript and sdk/python. They provide pagination, typed instruments, bounded retries, timeouts, and research job start, status, cancellation, and bounded polling, webhook endpoint management, and delivery history. The machine-readable OpenAPI 3.1 contract is available in the Tidelight repository. Packages are not published yet; follow each package README for local installation and usage.

Current availability

This release covers supported tokenized equity instrument discovery, organization scoped developer access, credential usage, and asynchronous company snapshots. Public API redistribution terms for the Bitget backed market source remain pending review. Remote MCP is available at the documented endpoint. Webhook delivery is available for completed and failed research jobs. Billing is not active. TypeScript and Python clients exist in the repository but have not been published.