tradeproof 0.1.0

Official Python SDK for the TradeProof contractor-license API (v1, MVP).

tradeproof — Python SDK

Official Python SDK for the TradeProof contractor-license API (/v1). Hand-written, typed, and dependency-light (just httpx).

pip install tradeproof

Quickstart

from tradeproof import TradeProof

with TradeProof(api_key="tp_read_...") as client:
    results = client.licenses.search("roofing contractors in texas", limit=5)
    for hit in results.hits:
        print(hit.license_number, hit.business_name, hit.state)

    record = client.licenses.get("TX", "tdlr", "ABC123")
    print(record.status, record.expiration_date)

See examples/quickstart.py for an end-to-end example you can run against staging (TRADEPROOF_BASE_URL).

MVP scope — these features only

This is the 0.1.0 MVP. It intentionally covers a small, stable surface and nothing else:

• Authentication — API key (tp_...) or JWT bearer token; both sent as Authorization: Bearer.
• License lookup — client.licenses.get(...), .lookup(...), .search(...), .list(...), .coverage().
• Watchlist CRUD — client.watchlist.list() / .add() / .remove() (org-scoped; also needs internal_auth_token=).
• Webhook subscription CRUD — client.webhooks.create() / .list() / .get() / .update() / .delete().
• HMAC signature verification — tradeproof.verify(body, signature, secret) for the X-TradeProof-Signature header on inbound webhooks.

Everything else in the API (billing, audits, insurance/COI, notifications, Procore, admin) is out of scope for the MVP and lands in later minor releases.

Authentication

TradeProof(api_key="tp_read_...")          # programmatic API key
TradeProof(bearer_token="<jwt>")           # OIDC/JWT bearer
TradeProof(api_key="tp_...", internal_auth_token="...")  # org-scoped surfaces (watchlist)

Webhook signature verification (HMAC)

verify() is the cryptographic primitive that authenticates a webhook body — it confirms the payload was signed with your subscription secret and is within the replay-tolerance window. It does not assert anything about a contractor.

import tradeproof

ok = tradeproof.verify(request.body, request.headers["X-TradeProof-Signature"], secret)
if not ok:
    abort(400)

The signature is t=<unix>,v1=<hex> where v1 = HMAC-SHA256(secret, f"{t}.{body}"); during secret rotation several v1= values may be present and any valid one is accepted.

Errors & retries

Non-2xx responses raise typed exceptions (NotFoundError, AuthenticationError, RateLimitError, ...), all subclasses of tradeproof.APIError. The client automatically retries on 429 (honouring Retry-After) and 5xx, up to max_retries (default 2).

Roadmap to 1.0

Milestone	Adds
0.2.0	Async client (AsyncTradeProof), auto-pagination iterators
0.3.0	Insurance/COI + audit-report read surfaces
0.4.0	Notifications + billing read surfaces
1.0.0	Full /v1 coverage, frozen public surface, stability commitment

Versioning & stability

Pre-1.0 the SDK follows tight semantic-versioning discipline so you can pin safely:

• 0.1.x — bug-fix patches only; no breaking changes.
• 0.2.0, 0.3.0, ... — additive minor releases; existing calls keep working.
• 1.0.0 — the stability commitment: the public surface is frozen and any future breaking change ships with a 12-month deprecation window and a migration note.

Until 1.0.0, pin a minor range (e.g. tradeproof>=0.1,<0.2).

License

Apache-2.0.