kestrel-feature-wallet 0.1.2

Multi-currency agent wallet with Stripe on-ramp for Kestrel Sovereign

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

uv pip install kestrel-feature-wallet

With EVM chain support:

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

With Stripe on-ramp:

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

With x402 buyer support:

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

For local tests:

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.

!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.

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

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