Skip to content
Searches page titles, headings, and route paths. Press slash to focus.

Python and TypeScript SDKs

The official clients have one method for each route of the API. For Python: secblast 3.1.0 on PyPI. For TypeScript and JavaScript: @secblast/sdk 3.1.0 on npm. Each example shows what it printed.

Install

Needs Python 3.9 or later. It depends on httpx and typing_extensions.

Shell
pip install secblast
python -c "import secblast; print(secblast.__version__)"

Output:

Text
Successfully installed … secblast-3.1.0 typing-extensions-4.16.0
3.1.0

Create a client

The client reads your key from the SECBLAST_API_KEY environment variable and sends requests to https://api.secblast.com/v3. You can set both in the constructor, with the timeout and the number of retries.

Use the client in a with block, or call client.close() when done. AsyncSecBlastClient takes the same arguments; its methods are coroutines.

Python
import os
from secblast import SecBlastClient

client = SecBlastClient(
    api_key=os.environ["SECBLAST_API_KEY"],  # the default when left out
    base_url="https://api.secblast.com/v3",  # the default when left out
    timeout=60.0,
    max_retries=3,  # retries of 429 and 503 answers
)
print(client)
print(client.get_health()["status"])

Output:

Text
SecBlastClient(base_url='https://api.secblast.com/v3')
ok

Make a first call

Each route has one method, such as list_filings in Python and listFilings in TypeScript. Path parameters come first, in order. Query parameters use the API's names. In Python, from is from_, and camelCase names are snake_case. Each route's page shows its call in the Python SDK and TypeScript SDK tabs.

Python
from secblast import SecBlastClient

client = SecBlastClient()  # reads SECBLAST_API_KEY
page = client.list_filings(ticker="AAPL", form="10-K", limit=3)
for filing in page["data"]:
    print(filing["accession"], filing["filing_date"], filing["form_type"])
print(page["has_more"], page["next_cursor"])

Output:

Text
0000320193-26-000026 2026-11-03 10-K
0000320193-25-000079 2025-10-31 10-K
0000320193-24-000123 2024-11-01 10-K
True eyJhIjoiMDAwMDMy…

Answers are plain objects with the API's field names. Lists return one page: data, has_more, and next_cursor.

Page through results

Each list method has an iterator twin: iter_insider_transactions for list_insider_transactions, or iterInsiderTransactions for listInsiderTransactions. It follows next_cursor until has_more is false, one request per page, as you read. To get one page at a time, pass next_cursor as cursor.

Python
from itertools import islice
from secblast import SecBlastClient

client = SecBlastClient()
# iter_* follows next_cursor, one request per page, until has_more is false.
rows = client.iter_insider_transactions(issuer_ticker="AAPL", limit=100)
first_250 = list(islice(rows, 250))
print(len(first_250), first_250[-1]["accession"], first_250[-1]["transaction_date"])

# Or one page at a time:
page = client.list_filings(ticker="AAPL", form="10-K", limit=2)
next_page = client.list_filings(ticker="AAPL", form="10-K", limit=2, cursor=page["next_cursor"])
print([f["filing_date"] for f in next_page["data"]])

Output:

Text
250 0000320193-25-000032 2025-02-25
['2024-11-01', '2023-11-03']

Handle errors

An error answer raises an error whose class follows the HTTP status. It has status, code, detail, the request ID, and the whole problem body. code is stable. Errors lists the codes.

StatusError
400, 422ValidationError
401AuthenticationError
403PermissionDeniedError
404NotFoundError
409ConflictError
410GoneError
429RateLimitError
503ServiceUnavailableError
Other 5xxServerError
Python
from secblast import NotFoundError, SecBlastClient, ValidationError

client = SecBlastClient()
try:
    client.get_filing("0000320193-99-999999")
except NotFoundError as e:
    print(e.status, e.code, e.request_id)
    print(e.detail)

try:
    client.list_filings(ticker="NOPE")
except ValidationError as e:
    print(e.status, e.code, e.parameter)

Output:

Text
404 not_found f8b260547b193e45ff58ad85
no filing with accession 0000320193-99-999999
400 unknown_ticker ticker

A 429 or 503 answer is retried up to 3 times. The client waits for the Retry-After time, up to 60 seconds. A longer wait raises RateLimitError at once, with the wait in seconds (retry_after in Python, retryAfter in TypeScript). No answer at all (DNS, connection, or timeout) raises APIConnectionError.

Follow the filing stream

stream() reads GET /v3/stream and returns events as they arrive. It takes the stream's filters, such as forms, tickers, and items. Start it from a next_cursor you saved, or from now. Left out, it starts at the newest event.

Python
from itertools import islice
from secblast import SecBlastClient

client = SecBlastClient()
# after: a next_cursor you saved, or "now". Here: the oldest event the stream keeps.
saved = client.get_stream(wait=0)["retention"]["oldest_cursor"]
stream = client.stream(after=saved, forms="8-K", items="2.02")
for event in islice(stream, 3):  # without islice, the loop waits for new events
    filing = event["data"]["filing"]
    print(event["id"], event["type"], filing["accession"], filing["form_type"], filing["filing_date"])
# Save stream.cursor and pass it as after= to resume.

Output:

Text
str_000000000000255 filing.new 0001628280-26-069018 8-K 2026-11-03
str_000000000000538 filing.corrected 0000005272-26-000101 8-K 2026-11-03
str_000000000000985 filing.corrected 0002067876-26-000050 8-K 2026-11-03

The iterator's cursor moves to a page's next_cursor after the page's last event. Save it to resume there. A resumed stream can repeat the rest of a page, so handle each event id once. Stream has the events and filters.

Check webhook signatures

verify_webhook in Python and verifyWebhook in TypeScript check a delivery's webhook-id, webhook-timestamp, and webhook-signature headers against your endpoint's signing secret. They return the event. In TypeScript, import it from @secblast/sdk/webhooks (Node.js only).

  • Pass the body exactly as received. A body parsed and written out again does not verify.
  • A webhook-timestamp more than 5 minutes from your clock fails.
  • The webhook-id is the same on every attempt of a delivery. Use it to skip repeats.
Python
import os
from secblast import WebhookVerificationError, verify_webhook

SECRET = os.environ["SECBLAST_WEBHOOK_SECRET"]  # whsec_..., shown once when you create the endpoint

def handle(raw_body: bytes, headers: dict) -> int:
    try:
        event = verify_webhook(raw_body, headers, SECRET)
    except WebhookVerificationError as e:
        print("rejected:", e)
        return 400
    print("verified:", event["id"], event["type"])
    return 200

Output, for a delivery signed with a test secret, then with its body changed:

Text
verified: msg_test0001 filing.new
200
rejected: no matching v1 signature
400

Packages

Markdown version: /docs/sdks.md