Metadata-Version: 2.4
Name: blackswan-sdk
Version: 0.1.3
Summary: Official Python SDK for BlackSwan Finance
Author: BlackSwan Finance
License: MIT
Keywords: ethereum,defi,credit,web3,polygon,blackswan
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: web3>=7.0.0
Dynamic: license-file

# BlackSwan SDK for Python

SDK for interacting with BlackSwan Finance smart contracts.

## Installation

```bash
pip install blackswan-sdk
```

## Usage

```python
from blackswan import BlackSwanClient

# Amoy (Polygon testnet)
client = BlackSwanClient(
    network="amoy",
    rpc_url="https://polygon-amoy.g.alchemy.com/v2/your-api-key"
)

# Sepolia (Ethereum testnet)
client = BlackSwanClient(
    network="sepolia",
    rpc_url="https://eth-sepolia.g.alchemy.com/v2/your-api-key"
)

dashboard = client.get_credit_dashboard("0x...")
print(dashboard.trust_ratio)
```

## Methods

- `get_credit_dashboard(wallet)` - Returns CreditDashboard with all credit metrics
- `get_credit_dashboard_by_token_id(token_id)` - Same as above but looks up wallet by SBT token
- `get_reputation(wallet)` - Returns Reputation with score, tier, successful_loans, defaults, loans_taken
- `get_reputation_by_token_id(token_id)` - Same as above but looks up wallet by SBT token
- `get_credit_history(wallet)` - Returns aggregate loan data (loans_taken, total_borrowed, total_repaid)
- `has_soul(wallet)` - Returns True if wallet owns an SBT
- `token_of(wallet)` - Returns the SBT token ID for a wallet
- `get_trust_tier(wallet)` - Returns string tier (AAA, AA, A, BBB, BB, B)

### CreditDashboard Properties

| Property | Type | Description |
|----------|------|-------------|
| `trust_ratio` | int | Trust score (0-10000) |
| `current_apr` | int | Current APR index/risk increase in basis points (divide by 1000 for percentage) |
| `borrowed_usd` | int | Total USD borrowed |
| `repaid_usd` | int | Total USD repaid |
| `principal_repaid` | int | Principal repaid (from SBT contract) |
| `interest_repaid` | int | Interest repaid (from SBT contract) |
| `successful_loans` | int | Number of successful loans |
| `defaults` | int | Number of defaults |
| `tier` | int | User tier (0-4) |
| `trust_tier` | str | String representation of trust tier (AAA, AA, A, BBB, BB, B) |

### Reputation Properties

| Property | Type | Description |
|----------|------|-------------|
| `trust_ratio` | int | Trust score (0-10000) |
| `tier` | int | Tier based on repayment volume (0-4) |
| `successful_loans` | int | Number of on-time repayments |
| `defaults` | int | Number of defaults |
| `loans_taken` | int | Total loans taken |

### Example Usage

```python
from blackswan import BlackSwanClient

client = BlackSwanClient(
    network="amoy",
    rpc_url="https://polygon-amoy.g.alchemy.com/v2/your-api-key"
)

wallet = "0x..."

dashboard = client.get_credit_dashboard(wallet)
print(f"Trust: {dashboard.trust_ratio} ({dashboard.trust_tier})")
print(f"APR: {dashboard.current_apr / 1000}%")
print(f"Loans: {dashboard.successful_loans} successful, {dashboard.defaults} defaults")
```

