Metadata-Version: 2.4
Name: b402
Version: 1.2.0
Summary: b402 payments on BSC
Author-email: B402 <hello@b402.ai>
License: MIT
Project-URL: Homepage, https://b402.ai
Project-URL: Repository, https://github.com/b402-ai/b402-python
Project-URL: Documentation, https://github.com/b402-ai/b402-python#readme
Project-URL: Issues, https://github.com/b402-ai/b402-python/issues
Keywords: crypto,payment,bsc,gasless,binance,web3,blockchain
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: eth-account>=0.10.0
Requires-Dist: web3>=6.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: eth-utils>=2.0.0
Dynamic: license-file

# b402

Gasless crypto payments on BSC. One line of code.

## Install

```bash
pip install b402
```

## Fastest Way to Get Started

```bash
# 1. Set your private key
export PRIVATE_KEY="0x..."

# 2. Run Python
python3
```

```python
# 3. One line to pay!
from b402 import pay

result = pay(amount="0.01", token="USD1", recipient="0x...")
# Done! ✨
```

**That's it!**
- First payment: Auto-approves $10k cap + sends payment (~5 sec)
- Future payments: Just pays instantly (<3 sec, gasless!)

## What Just Happened?

1. Checked if USD1 is approved for B402 relayer
2. Approved $10,000 worth (one-time, costs ~$0.10 gas)
3. Sent your payment (gasless - relayer pays!)
4. Next 1000+ payments will be instant (no approval needed)

Defaults to BSC mainnet. Set `network="testnet"` for testnet.

### Manual Control (Optional)

```python
from b402 import B402

b402 = B402()

# Check approval status
approved, allowance = b402.check_approval("USD1")

# Manual setup if you prefer
if not approved:
    b402.setup("USD1")

# Send payment
result = b402.pay(amount="0.01", token="USD1", recipient="0x...")
```

## How It Works

**First Payment:**
1. Checks if token has sufficient allowance for this payment
2. If not, automatically approves up to $10,000 worth (costs ~$0.10 gas, one-time)
3. Sends payment (gasless!)

**Subsequent Payments:**
1. Uses existing allowance ✅
2. Sends payment immediately (gasless!)
3. Re-approves automatically if allowance runs low

All payments are **gasless** for the user - the relayer pays all gas fees.

### Security

**Smart Approval Limits:**
- Never approves infinite amounts
- Default cap: $10,000 worth of tokens
- Checks allowance before each payment
- Only approves when needed

**Before (unsafe):**
```python
# Many SDKs approve: 2^256-1 (infinite!)
approve(relayer, 115792089237316195423570985008687907853269984665640564039457584007913129639935)
```

**B402 (safe):**
```python
# Approves: $10,000 worth (reasonable limit)
approve(relayer, 10000000000000000000000)  # 10,000 * 10^18
```

### Examples

**Simplest (auto-approval):**
```python
from b402 import pay

result = pay("0.01", "USD1", "0x...")
# First time: approves + pays
# After that: just pays (gasless)
```

**Disable auto-approval:**
```python
result = pay("0.01", "USD1", "0x...", auto_approve=False)
# Will return error if not approved, prompting manual setup
```

**Manual control:**
```python
from b402 import B402

b402 = B402()
b402.setup("USD1")  # Explicit one-time setup
result = b402.pay("0.01", "USD1", "0x...")
```

Run the complete demo: `python examples/complete_demo.py`

## Supported Tokens

**Mainnet:** USD1, USDT, USDC
**Testnet:** USDT

## 30-Second Tutorial

```python
# Install
# pip install b402

# Set key
import os
os.environ["PRIVATE_KEY"] = "0x..."

# Pay (that's it!)
from b402 import pay
result = pay("0.01", "USD1", "0x...")

# Check result
print(result.tx_hash if result.success else result.error)
```

Copy, paste, done. 🚀

## API Reference

### `pay()` - Simplest

```python
from b402 import pay

result = pay(
    amount="0.01",           # Amount to send
    token="USD1",            # USD1, USDT, or USDC
    recipient="0x...",       # Recipient address
    network="mainnet",       # Optional: "mainnet" or "testnet"
    auto_approve=True,       # Optional: Auto-approve if needed
    debug=False              # Optional: Show debug logs
)
```

### `B402()` - Advanced

Create B402 client for manual control. Defaults to mainnet.

```python
b402 = B402()  # mainnet
b402_test = B402(network="testnet")
```

### `b402.setup(token)`

One-time setup: approve relayer to spend tokens.

```python
result = b402.setup("USD1")
# Returns: {"approved": True, "allowance": int, "tx_hash": "0x..."}
```

### `b402.check_approval(token)`

Check if token is approved.

```python
approved, allowance = b402.check_approval("USD1")
```

### `b402.pay(amount, token, recipient)`

Send gasless payment.

```python
result = b402.pay(amount="0.01", token="USD1", recipient="0x...")
# Returns: PaymentResult(success, tx_hash, error, payer, recipient, amount, token)
```

### `pay()` - One-liner

Factory function for simple usage (after setup).

```python
from b402 import pay

result = pay(amount="0.01", token="USD1", recipient="0x...")
```

## Environment Variables

- `PRIVATE_KEY` - Required. Your wallet private key (with 0x prefix)

## Examples

- [examples/complete_demo.py](examples/complete_demo.py) - Full workflow with setup
- [examples/one_liner.py](examples/one_liner.py) - Simplest payment
- [examples/check_approval.py](examples/check_approval.py) - Check approval status

## Network Details

**BSC Mainnet** (Chain ID: 56)
- Relayer: `0xE1C2830d5DDd6B49E9c46EbE03a98Cb44CD8eA5a`
- USD1: `0x8d0d000ee44948fc98c9b98a4fa4921476f08b0d`
- USDT: `0x55d398326f99059fF775485246999027B3197955`
- USDC: `0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d`

**BSC Testnet** (Chain ID: 97)
- Relayer: `0x62150F2c3A29fDA8bCf22c0F22Eb17270FCBb78A`
- USDT: `0x337610d27c682E347C9cD60BD4b3b107C9d34dDd`

## License

MIT
