oilflow 0.1.0

Official Python SDK for the OilFlow Network compliance APIs.

oilflow (Python SDK)

Official Python SDK for the OilFlow Network compliance APIs.

• Regulatory Matrix (235 jurisdictions)
• KYC-as-API + UBO + multilingual Adverse Media
• Scam Cluster Intelligence Feed
• Webhooks with HMAC verification helper (raw / Slack / Teams formats)
• Regulator-ready reports (FATF Rec.10, FinCEN CDD, EU 6AMLD, FCA SYSC 18, MAS 626, OFSI)
• LC discrepancy detection (UCP 600)
• Customer watchlist sync
• Paginated audit log streaming

Built-in retry with jittered exponential backoff for 5xx + 429 responses (Retry-After respected). Python 3.9+.

Install

pip install oilflow

Quick start

from oilflow import Client

client = Client()  # reads OILFLOW_API_KEY from env

result = client.kyc.screen(
    company_name="Acme Trading FZE",
    country="UAE",
    directors=["Jane Doe"],
)
print(result["verdict"])         # "pass" / "review" / "fail"
print(result["screening_run_id"])

Regulatory check

check = client.regulatory.check(
    country="Kenya",
    product="crude",
    listing_type="demand",
)
if not check["allowed"]:
    for blocker in check["blockers"]:
        print(blocker["reason"])

Verify a webhook delivery

from oilflow import verify_webhook_signature

@app.route("/webhooks/oilflow", methods=["POST"])
def webhook():
    raw = request.get_data()
    if not verify_webhook_signature(
        raw,
        request.headers.get("X-OilFlow-Signature"),
        OILFLOW_WEBHOOK_SECRET,
    ):
        abort(401)
    # process request.json

Subscribe to webhook events

sub = client.webhooks.create(
    url="https://your-app.example.com/webhooks/oilflow",
    events=["kyc.match_detected", "cluster.entity_added"],
    description="Compliance war-room",
)
# sub["secret"] is shown once; store it in your secret manager

For Slack/Teams native rendering, set delivery_format="slack" (URL must be a hooks.slack.com incoming webhook) or "teams" (webhook.office.com). OilFlow renders the payload as Block Kit / Adaptive Card on the server — no HMAC secret is issued.

Stream the audit log

for page in client.audit.pages(days=90):
    print(f"page: {page['count']} rows")
    # ship to your warehouse

Configuration

Client(
    api_key="oilflow_live_...",       # or OILFLOW_API_KEY env var
    base_url="https://oilflow.us",    # or OILFLOW_BASE_URL env var
    max_retries=5,
    base_retry_delay=0.25,
    timeout=30.0,
)

Error handling

from oilflow import OilFlowApiError

try:
    client.kyc.screen(company_name="...")
except OilFlowApiError as e:
    print(e.status_code, e.error_code, e.request_id)

error_code is a stable, branchable identifier (auth_required, scope_denied, rate_limited, invalid_param, etc.).

Sandbox

Get a free sandbox key (7-day, 100 calls/day, read-only) without signup at https://oilflow.us/sandbox. Pass it as api_key to evaluate the API end-to-end before upgrading.

Documentation

• Full API reference: https://oilflow.us/api-docs
• OpenAPI 3.1 spec: https://oilflow.us/openapi.yaml

License

Apache-2.0.