Python SDK

Official Python client for the Huntrecht Platform API v1.

Installation

pip install huntrecht-sdk

Quick Start

from huntrecht import HuntrechtClient

client = HuntrechtClient(
    client_id="hnt_your_client_id",
    client_secret="your_secret"
)

# Authenticate (automatic on first request)
tokens = client.auth.token()
print(f"✓ Authenticated (expires in {tokens['expires_in']}s)")

# List orders
orders = client.orders.list(status="pending")
for order in orders["data"]:
    print(f"Order {order['id']}: {order['commodity']} - {order['quantity']}")

# Get credit score
score = client.credit.score("customer@example.com")
print(f"Credit score: {score['data']['credit_score']} ({score['data']['risk_level']})")

Authentication

# Using environment variables
client = HuntrechtClient()

# Using explicit credentials
client = HuntrechtClient(
    client_id="hnt_your_client_id",
    client_secret="your_secret"
)

# With custom base URL
client = HuntrechtClient(
    base_url="https://api.huntrecht.com",
    client_id="hnt_abc",
    client_secret="secret"
)

Resource Modules

Auth

# Get access token
tokens = client.auth.token()

# Refresh token
tokens = client.auth.token(grant_type="refresh_token", refresh_token="...")

# Revoke token
client.auth.revoke()

API Clients

# List API clients
clients = client.clients.list(user_id=1)

# Create API client (secret shown only once)
new_client = client.clients.create(
    user_id=1,
    client_name="My Integration",
    scopes=["read", "orders:read", "orders:write"],
)
print(f"Secret: {new_client['client_secret']}")

# Rotate secret
rotated = client.clients.rotate_secret(user_id=1, client_id="hnt_abc")

# Delete client
client.clients.delete(user_id=1, client_id="hnt_abc")

Orders

# List orders
orders = client.orders.list(page=1, per_page=20, status="pending")

# Get order
order = client.orders.get("ord_abc123")

# Create order
order = client.orders.create(
    commodity="Gold",
    quantity=100,
    delivery_terms="FOB",
    destination="New York",
)

Payments

# List payments
payments = client.payments.list(status="completed")

# Get payment
payment = client.payments.get("pay_abc123")

# Create payment
payment = client.payments.create(
    subscription_id=123,
    amount=2500.00,
    currency="USD",
    payment_method="card",
)

Subscriptions

# List subscriptions
subs = client.subscriptions.list(status="active", include_payment_history=True)

# Get subscription
sub = client.subscriptions.get("sub_abc123")

Credit Risk

# Get credit score
score = client.credit.score("customer@example.com")

# Assess credit
assessment = client.credit.assess(
    customer_email="customer@example.com",
    include_recommendations=True,
)

KYC

# List KYC submissions
kycs = client.kyc.list(status="pending")

# Submit KYC
result = client.kyc.submit(
    company_name="Acme Corp",
    company_type="LLC",
    registration_number="123456789",
)

Quotes

# List quotes
quotes = client.quotes.list()

# Request quote
quote = client.quotes.create(
    commodity="Copper",
    quantity=500,
    unit="kg",
    delivery_location="Shanghai",
)

Users

# Get current user
me = client.users.me()

# Get user by ID
user = client.users.get("user_123")

Storefront

# List collections
collections = client.storefront.collections(include_products=True)

# Get collection
collection = client.storefront.collection("b2b-wholesale")

# List products
products = client.storefront.products(b2b_only=True)

# Search products
results = client.storefront.search("copper wire", b2b_only=True)

Price Drops (Public)

# List recent price drops
drops = client.price_drops.list(limit=10, min_discount=5.0)

# Featured price drops
featured = client.price_drops.featured()

Linked Payments

# Check eligibility
eligibility = client.linked_payments.check_eligibility("cust_123")

# Link wallet
wallet = client.linked_payments.link_wallet(
    customer_id="cust_123",
    wallet_address="0xabc...",
    wallet_provider="metamask",
)

# Link bank
bank = client.linked_payments.link_bank(
    customer_id="cust_123",
    plaid_access_token="access-sandbox-...",
)

# Get linked accounts
accounts = client.linked_payments.linked_accounts("cust_123")

Error Handling

from huntrecht import (
    HuntrechtError,
    AuthenticationError,
    RateLimitError,
    NotFoundError,
    ValidationError,
    PermissionError,
)

try:
    orders = client.orders.list()
except AuthenticationError as e:
    print(f"Auth failed: {e}")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except PermissionError as e:
    print(f"Insufficient permissions: {e}")
except NotFoundError as e:
    print(f"Resource not found: {e}")
except ValidationError as e:
    print(f"Validation failed: {e}")
except HuntrechtError as e:
    print(f"API error: {e} (status={e.status_code})")

Environment Variables

Variable	Description
HUNTRECHT_BASE_URL	API base URL (default: https://api.huntrecht.com)
HUNTRECHT_CLIENT_ID	OAuth2 client ID
HUNTRECHT_CLIENT_SECRET	OAuth2 client secret

Rate Limits

Rate limits are based on your subscription plan. The SDK handles 429 responses automatically with exponential backoff.

Plan	Requests/Minute
Starter	60
Basic	300
Standard	1,000
Pro	3,000
Enterprise	10,000