Skip to content

About

Official Python client for the Tidelight API and developer ecosystem.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Tidelight

Tidelight Python SDK

Typed access to Tidelight Intelligence Cloud API v1.

Product · API guide · canonical repository

简体中文版本 / Chinese README


The official Python client supports tokenized-equity market listings, asynchronous company research jobs, synchronous AgentKey research, research webhooks, and read-only public Decision Capsule verification. It preserves provider provenance, stable error codes, and request IDs while applying bounded timeouts and retries.

Install

python -m pip install tidelight==0.1.2

Keep the project API key in trusted server code. Market calls require market:read; research calls require research:run; webhook calls require alerts:manage.

Quickstart

import os
from tidelight import Client

client = Client(os.environ["TIDELIGHT_API_KEY"])
page = client.list_tokenized_equities(limit=20, underlying_ticker="AAPL")

for instrument in page.data:
    print(instrument.symbol, instrument.underlying_ticker)

Supported workflows

Workflow Scope Client methods
Tokenized-equity spot listings and pagination market:read list_tokenized_equities, tokenized_equities
Company research snapshots research:run start_company_research, get_research_job, cancel_research_job, wait_for_research_job
AgentKey research across discovered read-only tools research:run research_with_agentkey
Research webhooks and delivery history alerts:manage create_webhook, update_webhook, list_webhooks, list_webhook_deliveries
Public Decision Capsule copies Public bearer link get_public_decision_capsule, verify_public_decision_capsule

A tokenized-equity spot instrument is not a direct share or a stock perpetual. When provider terms block a market response, the SDK surfaces provider_terms_unconfirmed without retrying or substituting data.

AgentKey research is synchronous and is never automatically retried because upstream tools may consume credits:

result = client.research_with_agentkey(
    "Explain NVIDIA's stock reaction to its latest earnings using Yahoo Finance and Google News.",
    ticker="NVDA",
)
print(result["tools"], result["sources"])

The server selects and describes up to two relevant read-only AgentKey tools and returns cost and source provenance. Treat AgentKey data as untrusted external input. Your project key needs research:run; the AgentKey master key remains server-side.

Reliability and security

The default request timeout is 10 seconds. Network errors, 429, and transient 5xx responses receive at most two bounded retries. Webhook mutations are not automatically retried because the API does not accept webhook idempotency keys. The default transport rejects redirects and restricts bearer credentials to api.tidelight.app.

Public capsule links are fetched from tidelight.app without an API key and are verified locally against the disclosed snapshot's SHA-256 digest. public_base_url can be overridden only for a trusted HTTPS origin or local development. Digest verification detects changed bytes relative to the supplied digest; it does not prove authorship, source authenticity, or research quality.

Use the standalone helper to retrieve a shared capsule without creating an authenticated client:

import os
from tidelight import get_public_decision_capsule

capsule = get_public_decision_capsule(os.environ["TIDELIGHT_PUBLIC_CAPSULE_TOKEN"])
print(capsule["integrityHash"], capsule["snapshot"])

Webhook creation and secret rotation return a one-time signing secret. TODO: Persist it in your approved secret manager immediately. Do not print it; it cannot be recovered by listing the endpoint.

Build and test from source

python -m pip install -e ./sdk/python
PYTHONPATH=sdk/python/src python -m unittest discover -s sdk/python/tests -v

Canonical source lives in sdk/python in the canonical repository. The standalone Python repository is a synchronized source mirror. Make source changes in the canonical repository.

Further reading

About

Official Python client for the Tidelight API and developer ecosystem.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages