SEC Blast Python SDK
The Python client for the SEC Blast v3 API: SEC EDGAR filings, documents, full-text search, XBRL financial data, ownership data, and the filing stream.
Version 1.0 targets the v3 API (https://api.secblast.com/v3). Versions 0.x targeted the v2 API.
Install
pip install secblast
It needs Python 3.9 or later. It depends on httpx and typing_extensions.
Quickstart
from secblast import SecBlastClient
client = SecBlastClient() # reads SECBLAST_API_KEY
page = client.list_filings(ticker="AAPL", form="10-K", limit=5)
for filing in page["data"]:
print(filing["accession"], filing["filing_date"])
The client
client = SecBlastClient(
api_key="sb_...", # an API key or an OAuth access token; default: SECBLAST_API_KEY
base_url="https://api.secblast.com/v3", # default: SECBLAST_BASE_URL, then this URL
timeout=60.0, # seconds
max_retries=3, # retries of 429 and 503 responses
max_retry_wait=60.0, # the longest Retry-After to wait for, in seconds
)
- The credential is sent as
Authorization: Bearer <credential>. - Use the client as a context manager (
with SecBlastClient() as client:), or callclient.close(). AsyncSecBlastClienttakes the same arguments. Its methods are coroutines, and itsiter_*methods andstream()are async iterators.
Methods
There is one method for each v3 operation, such as list_filings, get_filing, get_entity, search, get_income_statement, list_insider_transactions, and create_endpoint. Path parameters are positional. Query parameters are keyword arguments with the API's names. from is spelled from_, and camelCase names such as dateRange are snake_case (date_range). extra_params={...} sends parameters as given.
entity = client.get_entity("AAPL") # a CIK or a ticker
filing = client.get_filing("0000320193-26-000026")
hits = client.search(q='"going concern"', forms="10-K", filed_from="2024-01-01", limit=10)
income = client.get_income_statement("MSFT", period="annual", limit=5)
- List parameters take a list or a comma-separated string:
ticker=["AAPL", "MSFT"]andticker="AAPL,MSFT"are the same.TrueandFalseare sent astrueandfalse. Dates take a string or adatetime.date. - Responses are plain dicts.
secblast.modelshas a TypedDict for every schema in the OpenAPI document, so editors and type checkers know the keys.
Paging
List methods return one page: data, has_more, and next_cursor. Each paged method has an iter_* twin that follows next_cursor until has_more is false. It makes requests as you iterate.
for row in client.iter_insider_transactions(issuer_ticker="TSLA", filed_from="2025-01-01"):
print(row)
page = client.list_filings(cik=320193, limit=100)
next_page = client.list_filings(cik=320193, limit=100, cursor=page["next_cursor"])
Documents
docs = client.list_documents("0000320193-26-000026")["data"]
raw = client.get_document("0000320193-26-000026", "1") # bytes, as filed
text = client.get_document_text("0000320193-26-000026", "1") # str, the extracted text
pdf = client.get_document_pdf("0000320193-26-000026", "1") # bytes, a PDF of one document
whole = client.get_filing_pdf("0000320193-26-000026") # bytes, a PDF of the filing
with open("10-K.pdf", "wb") as f:
f.write(whole)
A document is named by its sequence number or its file name.
Errors
Every error response raises an APIError subclass built from the RFC 9457 problem body. It has status, code, detail, request_id, parameter, and the whole body in problem. code is stable.
| Status | Exception |
|---|---|
| 400, 422 | ValidationError (also BadRequestError) |
| 401 | AuthenticationError |
| 403 | PermissionDeniedError |
| 404 | NotFoundError |
| 409 | ConflictError |
| 410 | GoneError |
| 429 | RateLimitError, with retry_after in seconds |
| 503 | ServiceUnavailableError |
| other 5xx | ServerError |
No HTTP response (DNS, connection, or timeout) raises APIConnectionError. All of them are SecBlastError.
from secblast import SecBlastClient, ValidationError
try:
client.list_filings(ticker="NOPE")
except ValidationError as e:
print(e.status, e.code, e.detail, e.request_id) # 400 unknown_ticker ...
Retries: a 429 or 503 response is retried up to max_retries times. The client waits for Retry-After when the header is present and at most max_retry_wait seconds; a longer Retry-After raises the error at once. Without the header, it waits about 0.5, 1, 2, and 4 seconds. A GET that gets no response is retried the same way.
Stream
stream() long-polls GET /v3/stream and yields events as they arrive. It takes the get_stream filters (forms, tickers, ciks, items, types, and so on).
stream = client.stream(after=saved_cursor, forms=["8-K"], items=["2.02"])
for event in stream:
handle(event) # event["id"], event["type"], event["data"]["filing"]
save(stream.cursor) # where to resume
afteris anext_cursorfrom an earlier run, or"now". Left out, the stream starts at the newest event.stream.cursormoves to a page'snext_cursorafter the last event of that page. Resuming from it in the middle of a page delivers the rest of that page again. Each event has anid.- The iterator runs until you stop it. With
stop_when_caught_up=True, it stops when a page hashas_morefalse; addwait=0to return at once.
Webhooks
verify_webhook checks the webhook-id, webhook-timestamp, and webhook-signature headers of a delivery (Standard Webhooks v1) against the endpoint's signing secret and returns the parsed JSON body.
from secblast import verify_webhook, WebhookVerificationError
try:
event = verify_webhook(raw_body, request_headers, "whsec_...")
except WebhookVerificationError:
... # answer 400
raw_bodyis the request body as bytes, exactly as received; the signature covers<webhook-id>.<webhook-timestamp>.<body>. A body parsed and serialized again (request.json(),json.dumps) is not the signed byte sequence and does not verify; Flaskrequest.get_data()and Starletteawait request.body()return the bytes.- Signature check: base64(HMAC-SHA256) with the secret's bytes (the base64 after
whsec_), compared in constant time. The header holds one or more space-separatedv1,<signature>entries; two entries are sent while a rotated secret's previous value still signs, and the delivery verifies when any entry matches.secretcan also be a list ofwhsec_values. - Tolerance: the
webhook-timestampmust be within 5 minutes of the clock (tolerance_s=300;now=sets the reference time, in Unix seconds). A non-finite or negativetolerance_s, or a non-finitenow, raisesWebhookVerificationError. SEC Blast stamps every attempt with its own time. - Deduplication: the
webhook-idis the same on every attempt of a delivery, and is theidin the body. - Raises
WebhookVerificationErrorfor a missing header, a timestamp outside the tolerance, no matchingv1signature, a secret that is not awhsec_value, or a body that is not a JSON object.
License
MIT
Metadata
Release files for secblast 3.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| secblast-3.1.0.tar.gz | 122.6 kB | Without provenance | Details for secblast-3.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| secblast-3.1.0-py3-none-any.whl | Python 3 | none | any | Details for secblast-3.1.0-py3-none-any.whl |
Total release size: 256.7 kB
Release files / secblast-3.1.0.tar.gz
| Download URL | secblast-3.1.0.tar.gz |
|---|---|
| Size | 122.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
121460d06ebbe273cdba601eaece8ecd7e5217e756f97dff585f1efd6219f15d
|
|
BLAKE2b-256 checksum How to use checksums |
5b7211a93013db02dad8c724de134b68e0eb0116d2a586a0d9f8ca222c97cb75
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.15
|
Release files / secblast-3.1.0-py3-none-any.whl
| Download URL | secblast-3.1.0-py3-none-any.whl |
|---|---|
| Size | 134.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
93b9556ee95c512c4bbcebf0bdafa6647f9488a6b1f58d92e7326e434443671e
|
|
BLAKE2b-256 checksum How to use checksums |
2bb0fa0a9ae1490e93f5edae7b309cf381076da3c8d54500db977f5e46e0fcb4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.15
|
Security for secblast 3.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.