> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fincept.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Credit System

> How credits work, deduction logic, and balance management

# Credit System

Fincept uses a credit-based system where each API call consumes credits based on computational complexity. This guide explains how credits work, when they're deducted, and how to manage your balance.

## How Credits Work

### Credit as Currency

Credits are the **unit of payment** for API calls:

| Tier     | Credits per Request | Computational Cost    |
| -------- | ------------------- | --------------------- |
| Free     | 0                   | Lightweight utilities |
| Basic    | 1                   | Simple calculations   |
| Standard | 2                   | Moderate complexity   |
| Pro      | 5                   | Advanced models & ML  |

### Deduction Timing

```mermaid theme={null}
graph LR
    A[API Request] --> B{Validate}
    B -->|Invalid| C[Error - 0 credits]
    B -->|Valid| D[Execute]
    D -->|Success| E[Deduct Credits]
    D -->|Error| F[Error - 0 credits]
    E --> G[Return Results]
```

<Info>
  **Credits are only deducted on successful requests.** Failed requests cost nothing!
</Info>

### What Counts as Success?

**Credits Deducted (200 OK):**

```json theme={null}
{
  "success": true,
  "data": {"price": 42.50}
}
```

**No Credits Deducted (4xx/5xx errors):**

```json theme={null}
{
  "success": false,
  "message": "Invalid parameters"
}
```

## New User Credits

### Free Account Bonus

Every registered account gets:

**350 Credits** that **NEVER EXPIRE**

```bash theme={null}
# Register
curl -X POST https://api.fincept.in/user/register \
  -H "Content-Type: application/json" \
  -d '{"username": "john", "email": "john@example.com", "password": "Pass123!"}'

# After verification: credit_balance = 350
```

**What 350 credits get you:**

* Unlimited Free tier calls (0 credits each)
* 350 Basic tier calls (1 credit each)
* 175 Standard tier calls (2 credits each)
* 70 Pro tier calls (5 credits each)
* Or any combination!

### Guest Account Credits

**50 Credits** for 24-hour testing:

```bash theme={null}
curl -X POST https://api.fincept.in/guest/create \
  -H "Content-Type: application/json" \
  -d '{"device_id": "test-device"}'
```

<Warning>
  Guest credits expire after 24 hours and **cannot be topped up**. Register for permanent 350 credits!
</Warning>

## Checking Your Balance

### View Current Balance

```bash theme={null}
curl https://api.fincept.in/user/profile \
  -H "X-API-Key: fk_user_your_key"
```

**Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "username": "johndoe",
    "credit_balance": 284.5,
    "account_type": "free"
  }
}
```

### Usage History

Track credit consumption over time:

```bash theme={null}
curl https://api.fincept.in/user/usage \
  -H "X-API-Key: fk_user_your_key"
```

**Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "period": "last_30_days",
    "total_requests": 127,
    "total_credits_used": 65.5,
    "current_balance": 284.5,
    "endpoint_usage": {
      "/quantlib/pricing/black-scholes": {
        "count": 45,
        "credits": 90
      }
    }
  }
}
```

## Credit Deduction Logic

### Database-Level Protection

Credits **cannot go negative** - system prevents overdraft:

```python theme={null}
# Internal logic (for reference)
if user.credit_balance < required_credits:
    raise InsufficientCreditsError

# Atomic deduction with floor at 0
user.credit_balance = max(0, user.credit_balance - credits)
```

### Insufficient Credits Error

```json theme={null}
{
  "success": false,
  "message": "Insufficient credits",
  "detail": "Required: 5 credits, Available: 2 credits. Please purchase a new plan to continue."
}
```

**HTTP Status:** 402 Payment Required

### Race Condition Protection

Multiple simultaneous requests are handled safely:

```
Request A (5 credits) + Request B (5 credits) with balance = 7 credits

 Request A succeeds → Balance = 2
 Request B fails (insufficient) → Balance stays 2
```

## Credit Expiry

### Never Expire

Free account signup credits (350)
One-time credit purchases
Unused subscription credits carry forward (if subscription active)

### Monthly Expiry

Subscription credits refresh monthly:

```
Jan 1: +500 credits (subscription)
Jan 15: Used 200 credits → Balance = 300
Feb 1: Balance resets to 500 (Jan credits lost)
```

<Tip>
  Mix subscriptions with one-time purchases: subscription for regular usage, one-time for overflow that never expires!
</Tip>

### After Subscription Ends

```
Active subscription: 500 credits/month
↓
Subscription expires
↓
Auto-downgrade to free tier: +350 credits (never expire)
```

## Topping Up Credits

### Buy One-Time Credits

```bash theme={null}
curl -X POST https://api.fincept.in/cashfree/create-order \
  -H "X-API-Key: fk_user_your_key" \
  -H "Content-Type: application/json" \
  -d '{"plan_id": "credits_500"}'
```

[View credit packages →](/subscription-plans#one-time-purchases)

### Subscribe for Monthly Credits

```bash theme={null}
curl -X POST https://api.fincept.in/cashfree/create-order \
  -H "X-API-Key: fk_user_your_key" \
  -H "Content-Type: application/json" \
  -d '{"plan_id": "basic_monthly"}'
```

[View subscription plans →](/subscription-plans)

## Credit Optimization

### 1. Use Free Tier When Possible

Many utility functions cost 0 credits:

```bash theme={null}
# FREE - Check business day
POST /quantlib/core/date/is-business-day

# FREE - Parse date
POST /quantlib/core/date/parse

# 2 CREDITS - Price option
POST /quantlib/pricing/black-scholes
```

### 2. Choose Right Tier

Don't overpay for simple operations:

**Bad (5 credits):**

```bash theme={null}
# Using Pro tier for simple mean
POST /quantlib/risk/var # Overkill!
```

**Good (1 credit):**

```bash theme={null}
# Using Basic tier
POST /quantlib/statistics/mean # Perfect!
```

### 3. Batch Operations

Design workflows to minimize API calls:

**Inefficient (10 credits):**

```
5 separate calls × 2 credits = 10 credits
```

**Efficient (2 credits):**

```
1 call with batch parameters × 2 credits = 2 credits
```

### 4. Cache Results

Store frequently used results locally:

```python theme={null}
# Cache yield curve (2 credits once)
curve = api.build_curve(...)
cache.set("yield_curve_2024", curve, ttl=3600)

# Reuse for multiple bonds (0 extra credits)
for bond in bonds:
    price = api.price_bond(bond, curve=cached_curve)
```

## Transaction History

View all credit movements:

```bash theme={null}
curl https://api.fincept.in/user/transactions \
  -H "X-API-Key: fk_user_your_key"
```

**Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "transactions": [
      {
        "id": 123,
        "transaction_id": "txn_abc123",
        "amount_inr": 4.99,
        "credits_purchased": 500,
        "status": "completed",
        "created_at": "2024-01-15T10:30:00Z"
      }
    ]
  }
}
```

## FAQs

<AccordionGroup>
  <Accordion title="Do credits rollover to next month?">
    **Subscription credits**: No, they reset monthly

    **One-time credits**: Yes, they never expire
  </Accordion>

  <Accordion title="What happens if I run out?">
    API calls fail with 402 error. Purchase more credits to continue.
  </Accordion>

  <Accordion title="Are failed requests charged?">
    No! Only successful requests (200 OK) consume credits.
  </Accordion>

  <Accordion title="Can I get a refund for unused credits?">
    No, credits are non-refundable once purchased.
  </Accordion>

  <Accordion title="How do I track credit usage?">
    Use `/user/usage` endpoint for detailed analytics by endpoint and time period.
  </Accordion>

  <Accordion title="Can credits go negative?">
    No, the system prevents negative balances. Requests fail if insufficient credits.
  </Accordion>

  <Accordion title="Do enterprise accounts use credits?">
    Enterprise accounts have unlimited access without credit deduction (custom pricing).
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Subscription Plans" icon="credit-card" href="/subscription-plans">
    Compare monthly subscription options
  </Card>

  <Card title="Pricing Overview" icon="tag" href="/pricing">
    Complete pricing information
  </Card>

  <Card title="Billing FAQ" icon="circle-question" href="/billing-faq">
    Common billing questions
  </Card>

  <Card title="Tier System" icon="layer-group" href="/tier-system">
    Understand tier access control
  </Card>
</CardGroup>