# 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

### Python

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

```bash
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
```

### TypeScript

Runs on Node.js 18 or later, Deno, Bun, and browsers. It has no runtime dependencies and ships ES modules, CommonJS, and type declarations.

```bash
npm install @secblast/sdk
npm ls @secblast/sdk
```

Output:

```text
added 1 package in 484ms
…
`-- @secblast/sdk@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.

### Python

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
```

### TypeScript

The client uses the built-in `fetch`. Pass `fetch` in the options to use another.

```typescript
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:

```text
{ baseUrl: '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

```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…
```

### TypeScript

```typescript
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:

```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

```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']
```

### TypeScript

```typescript
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:

```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](https://www.secblast.com/docs/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` |

### Python

```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
```

### TypeScript

```typescript
import { 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:

```text
404 not_found 656f78bd9331288787a41c75
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`](https://www.secblast.com/docs/reference/get-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

```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
```

### TypeScript

```typescript
import { 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:

```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](https://www.secblast.com/docs/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

```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
```

### TypeScript

```typescript
import { 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:

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

## Packages

- Python: [`secblast` on PyPI](https://pypi.org/project/secblast/)
- TypeScript: [`@secblast/sdk` on npm](https://www.npmjs.com/package/@secblast/sdk)
