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.

How the platform fits together

Supported provider data and research sources feed shared Tidelight services. Server-side authorization applies tenant membership, credential scopes, quotas, and audit before an API or MCP response is returned. The developer console gives account owners and project members access to their own activity.

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. When licensed and enabled, prices are Bitget tokenized equity spot prices; they are not direct US stock quotes. Until redistribution terms are confirmed, this endpoint is fail-closed and returns `provider_terms_unconfirmed`.

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 or unconfirmed provider redistribution terms returns 503 (`provider_unavailable` or `provider_terms_unconfirmed`). 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.

MCP client compatibility

Tidelight uses Streamable HTTP at https://mcp.tidelight.app/mcp and supports bearer authorization plus OAuth discovery. MCP Inspector 2.11.0 has a recorded authenticated production connection and scoped market-tool call. Client compatibility still depends on each app’s Streamable HTTP and authorization flow; use its remote MCP connection settings with the endpoint and a Tidelight OAuth grant where supported. We have not verified Claude Desktop, Cursor, VS Code, or FastMCP with an authenticated Tidelight tool call, so they are not listed as tested clients. The official Python MCP SDK currently has an unauthenticated challenge check only. This status will be updated as authenticated client tests complete.

SDKs

Browse the official package directory for live versions, installation commands, and package guides. 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. The TypeScript package is published as `@tidelight/sdk` and the Python package as `tidelight`; install commands and current versions are shown in the package directory.

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 are available from npm and PyPI; review their package pages for release details and installation.