Credit System¶

Credits are the currency of Circuit KYC. Every API operation costs a certain number of credits.

How Credits Work¶

Purchase credits via the dashboard or API
Use credits when making API calls
Monitor usage in real-time
Auto-recharge to never run out

Credit Costs by Operation¶

Operation	Credits	Notes
`check-eligibility`	1	Most common operation
`assess-risk`	5	Includes multiple checks
`issue`	10	Creates signed credential
`verify`	1	Validates credential
`ingest`	0	Free to encourage data sharing

Checking Your Balance¶

APIPythonDashboard

curl https://api.circuitkyc.com/billing/credits \
  -H "X-API-Key: sk_live_your_api_key"

Response:

{
  "credits": 8500,
  "tier": "starter"
}

balance = client.billing.get_credits()
print(f"Credits remaining: {balance.credits}")

View your credit balance at dashboard.circuitkyc.com

Purchasing Credits¶

Via API¶

curl -X POST https://api.circuitkyc.com/billing/checkout/credits \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "package": "large",
    "success_url": "https://yourapp.com/success",
    "cancel_url": "https://yourapp.com/cancel"
  }'

You'll receive a Stripe checkout URL to complete payment.

Via Dashboard¶

Log in to dashboard.circuitkyc.com
Click Buy Credits
Select package size
Complete payment

Auto-Recharge¶

Configure automatic credit purchases when balance gets low:

client.billing.configure_auto_recharge(
    enabled=True,
    threshold=500,    # Recharge when below 500 credits
    package="small"   # Purchase 1,000 credits
)

Best Practices¶

Set threshold to cover ~1 day of usage
Use small package for predictable spend
Use large package for high-volume applications

Credit Deduction¶

Credits are deducted synchronously when you make an API call:

Request received
Credits checked (sufficient balance?)
Credits deducted
Operation performed
Response returned

If you don't have enough credits, you'll receive:

{
  "detail": "Insufficient Credits - Payment Required"
}

HTTP Status: 402 Payment Required

Refunds¶

Credits are refunded automatically for:

5xx errors - Server errors refund full credit cost
Timeout errors - Network issues refund credits

Credits are not refunded for:

4xx client errors (invalid input, auth failures)
Successful requests with "not found" results

Usage Tracking¶

Daily Usage¶

curl "https://api.circuitkyc.com/billing/usage?days=7" \
  -H "X-API-Key: sk_live_your_api_key"

Transaction History¶

curl "https://api.circuitkyc.com/billing/transactions?limit=50" \
  -H "X-API-Key: sk_live_your_api_key"

Low Balance Alerts¶

We send email alerts when:

20% remaining - Warning alert
5% remaining - Critical alert
0 credits - Out of credits

Configure alert thresholds in your dashboard settings.

Credits vs Subscriptions¶

Feature	Credits	Subscription
API access	Required	Not required
Rate limits	N/A	Higher with paid tiers
Support	Email	Priority with Growth+
Expires	Never	Monthly

You need both credits for API usage and an optional subscription for higher rate limits and support.

FAQ¶

What happens to unused credits? They never expire. Use them anytime.

Can I transfer credits between accounts? No, credits are tied to your API key.

Do sandbox credits work in production? No, sandbox credits only work in sandbox environment.

Minimum purchase? 1,000 credits ($120) is the minimum package.