Metadata-Version: 2.4
Name: kestrel-feature-wallet
Version: 0.1.2
Summary: Multi-currency agent wallet with Stripe on-ramp for Kestrel Sovereign
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: <3.14,>=3.11
Requires-Dist: aiosqlite>=0.21.0
Requires-Dist: cryptography>=45.0.5
Requires-Dist: httpx>=0.27.0
Requires-Dist: kestrel-sovereign-sdk<1,>=0.13
Provides-Extra: all
Requires-Dist: fastapi>=0.115.0; extra == 'all'
Requires-Dist: pytest-asyncio>=1.1.0; extra == 'all'
Requires-Dist: pytest-timeout>=2.3.1; extra == 'all'
Requires-Dist: pytest>=8.0.0; extra == 'all'
Requires-Dist: stripe>=10.0.0; extra == 'all'
Requires-Dist: web3>=7.0.0; extra == 'all'
Requires-Dist: x402[httpx]>=2.9.0; extra == 'all'
Provides-Extra: evm
Requires-Dist: web3>=7.0.0; extra == 'evm'
Provides-Extra: stripe
Requires-Dist: stripe>=10.0.0; extra == 'stripe'
Provides-Extra: test
Requires-Dist: fastapi>=0.115.0; extra == 'test'
Requires-Dist: pytest-asyncio>=1.1.0; extra == 'test'
Requires-Dist: pytest-timeout>=2.3.1; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Requires-Dist: stripe>=10.0.0; extra == 'test'
Requires-Dist: web3>=7.0.0; extra == 'test'
Requires-Dist: x402[httpx]>=2.9.0; extra == 'test'
Provides-Extra: x402
Requires-Dist: x402[httpx]>=2.9.0; extra == 'x402'
Description-Content-Type: text/markdown

# kestrel-feature-wallet

Multi-currency agent wallet with Stripe on-ramp for Kestrel Sovereign. Supports FIL, USDC, and USDT with on-chain balance sync, economic gates, cryostasis threshold monitoring, and fiat-to-crypto conversions via Stripe.

## Installation

```bash
uv pip install kestrel-feature-wallet
```

With EVM chain support:

```bash
uv pip install "kestrel-feature-wallet[evm]"
```

With Stripe on-ramp:

```bash
uv pip install "kestrel-feature-wallet[stripe]"
```

With x402 buyer support:

```bash
uv pip install "kestrel-feature-wallet[x402]"
```

For local tests:

```bash
uv pip install -e ".[all]"
uv run pytest
```

## Dependencies

- `kestrel-sovereign-sdk`
- `aiosqlite>=0.21.0`
- `httpx>=0.27.0`
- `cryptography>=45.0.5`
- Optional: `web3>=7.0.0` (via `[evm]`), `stripe>=10.0.0` (via `[stripe]`), `x402[httpx]>=2.9.0` (via `[x402]`)

## Usage

Once installed, the `WalletFeature` is automatically discovered by kestrel-sovereign via the `kestrel_sovereign.features` entry point.

## Configuration

| Variable | Description |
|----------|-------------|
| `KESTREL_DATA_KEY` | Enables encrypted private-key persistence for generated wallet keys |
| `KESTREL_DB_PATH` | Base directory for wallet key and audit storage when no agent DB path is available |
| `BASE_SEPOLIA_RPC` | Optional Base Sepolia RPC override; defaults to `https://sepolia.base.org` |
| `BASE_MAINNET_RPC` | Optional Base Mainnet RPC override; defaults to `https://mainnet.base.org` |
| `KESTREL_ALLOW_MAINNET` | Set to `true` or `1` only when the operator intentionally enables real-value mainnet transactions |
| `KESTREL_X402_MAX_USDC_PER_REQUEST` | Maximum x402 USDC invoice the buyer will sign; defaults to `1` |
| `KESTREL_TX_DAILY_LIMIT_USD` | Daily mainnet spending limit; defaults to `100` |
| `STRIPE_API_KEY` | Stripe API key (for on-ramp) |
| `STRIPE_WEBHOOK_SECRET` | Stripe webhook secret (for on-ramp) |

## Base L2 Commands

The Filecoin address and Base/EVM address are derived from the same secp256k1 key generated by `!wallet-generate-address`.

```text
!wallet-address
!wallet-chain-balance base_sepolia USDC
!wallet-chain-balance base_sepolia native
!wallet-send-token <to> <amount> USDC base_sepolia
```

Base Mainnet (`base_mainnet`) is blocked unless `KESTREL_ALLOW_MAINNET` is explicitly enabled.

For direct ERC-20 transfers, the wallet needs Base Sepolia ETH for gas and
Base Sepolia USDC for payments. For x402 exact payments through the default
testnet facilitator, Base Sepolia USDC can be enough because settlement can be
gas-sponsored by the facilitator. Filecoin Calibration FIL is a different
testnet asset and cannot pay Base Sepolia x402 invoices.
Current faucet references:

- Base Sepolia ETH: https://docs.base.org/base-chain/network-information/network-faucets
- Base Sepolia USDC: https://faucet.circle.com/

## x402 Buyer

`X402Buyer` wraps the Python x402 SDK with the agent's EVM private key and returns payment receipt metadata for audit trails.
It defaults to Base Sepolia and filters out Base Mainnet payment requirements unless `KESTREL_ALLOW_MAINNET` is explicitly enabled.

```python
from kestrel_feature_wallet import X402Buyer

buyer = X402Buyer(private_key="0x...")
paid = await buyer.post_with_payment("https://example.com/paid-upload", content=b"...")
print(paid.response.status_code)
print(paid.receipt)
```

Core storage integrations should use this buyer primitive instead of handling private keys directly.

## Development

```bash
uv pip install -e ".[test]"
uv run pytest
```
