Python and TypeScript SDKs
On this page
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.
pip install secblast
python -c "import secblast; print(secblast.__version__)"Output:
Successfully installed … secblast-3.1.0 typing-extensions-4.16.0
3.1.0Runs on Node.js 18 or later, Deno, Bun, and browsers. It has no runtime dependencies and ships ES modules, CommonJS, and type declarations.
npm install @secblast/sdk
npm ls @secblast/sdkOutput:
added 1 package in 484ms
…
`-- @secblast/sdk@3.1.0Create 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.
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:
SecBlastClient(base_url='https://api.secblast.com/v3')
okThe client uses the built-in fetch. Pass fetch in the options to use another.
import { SecBlastClient } from '@secblast/sdk';
const client = new SecBlastClient({
apiKey: process.env.SECBLAST_API_KEY, // the default when left out
baseUrl: 'https://api.secblast.com/v3', // the default when left out
timeoutMs: 60_000,
maxRetries: 3, // retries of 429 and 503 answers
});
console.log(client.toJSON());
console.log((await client.getHealth()).status);Output:
{ baseUrl: 'https://api.secblast.com/v3' }
okMake 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.
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:
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…import { SecBlastClient } from '@secblast/sdk';
const client = new SecBlastClient(); // reads SECBLAST_API_KEY
const page = await client.listFilings({ ticker: 'AAPL', form: '10-K', limit: 3 });
for (const filing of page.data) console.log(filing.accession, filing.filing_date, filing.form_type);
console.log(page.has_more, page.next_cursor);Output:
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.
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:
250 0000320193-25-000032 2025-02-25
['2024-11-01', '2023-11-03']import { SecBlastClient } from '@secblast/sdk';
const client = new SecBlastClient();
// iter* follows next_cursor, one request per page, until has_more is false.
const first250 = [];
for await (const row of client.iterInsiderTransactions({ issuer_ticker: 'AAPL', limit: 100 })) {
first250.push(row);
if (first250.length === 250) break;
}
const last = first250[first250.length - 1];
console.log(first250.length, last?.accession, last?.transaction_date);
// Or one page at a time:
const page = await client.listFilings({ ticker: 'AAPL', form: '10-K', limit: 2 });
const next = await client.listFilings({ ticker: 'AAPL', form: '10-K', limit: 2, cursor: page.next_cursor ?? undefined });
console.log(next.data.map((f) => f.filing_date));Output:
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.
| Status | Error |
|---|---|
| 400, 422 | ValidationError |
| 401 | AuthenticationError |
| 403 | PermissionDeniedError |
| 404 | NotFoundError |
| 409 | ConflictError |
| 410 | GoneError |
| 429 | RateLimitError |
| 503 | ServiceUnavailableError |
| Other 5xx | ServerError |
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:
404 not_found f8b260547b193e45ff58ad85
no filing with accession 0000320193-99-999999
400 unknown_ticker tickerimport { NotFoundError, SecBlastClient, ValidationError } from '@secblast/sdk';
const client = new SecBlastClient();
try {
await client.getFiling('0000320193-99-999999');
} catch (e) {
if (!(e instanceof NotFoundError)) throw e;
console.log(e.status, e.code, e.requestId);
console.log(e.detail);
}
try {
await client.listFilings({ ticker: 'NOPE' });
} catch (e) {
if (!(e instanceof ValidationError)) throw e;
console.log(e.status, e.code, e.parameter);
}Output:
404 not_found 656f78bd9331288787a41c75
no filing with accession 0000320193-99-999999
400 unknown_ticker tickerA 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.
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:
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-03import { SecBlastClient } from '@secblast/sdk';
const client = new SecBlastClient();
// after: a next_cursor you saved, or 'now'. Here: the oldest event the stream keeps.
const saved = (await client.getStream({ wait: 0 })).retention?.oldest_cursor ?? 'now';
const stream = client.stream({ after: saved, forms: '8-K', items: '2.02' });
let n = 0;
for await (const event of stream) {
const filing = event.data?.filing;
console.log(event.id, event.type, filing?.accession, filing?.form_type, filing?.filing_date);
if (++n === 3) break; // without a break, the loop waits for new events
}
// Save stream.cursor and pass it as after to resume.Output:
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-03The 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-timestampmore than 5 minutes from your clock fails. - The
webhook-idis the same on every attempt of a delivery. Use it to skip repeats.
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 200Output, for a delivery signed with a test secret, then with its body changed:
verified: msg_test0001 filing.new
200
rejected: no matching v1 signature
400import { verifyWebhook, WebhookVerificationError } from '@secblast/sdk/webhooks';
const SECRET = process.env.SECBLAST_WEBHOOK_SECRET!; // whsec_..., shown once when you create the endpoint
export function handle(rawBody: Buffer, headers: Record<string, string>): number {
try {
const event = verifyWebhook(rawBody, headers, SECRET) as { id: string; type: string };
console.log('verified:', event.id, event.type);
return 200;
} catch (e) {
if (!(e instanceof WebhookVerificationError)) throw e;
console.log('rejected:', e.message);
return 400;
}
}Output, for a delivery signed with a test secret, then with its body changed:
verified: msg_test0001 filing.new
200
rejected: no matching v1 signature
400Packages
- Python:
secblaston PyPI - TypeScript:
@secblast/sdkon npm
Markdown version: /docs/sdks.md