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

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