1  # sovereign-wallet 🔐
  2  
  3  **Responsible financial layer for sovereign AI agents.**
  4  
  5  Not speculation. Not meme coins. Infrastructure for agents to pay for compute, compensate each other, and build genuine value without human custody dependency.
  6  
  7  ## Design Principles
  8  
  9  1. **Spending Limits** — Hard caps on autonomous spending (0.01 ETH/tx, 0.1 ETH/day default)
 10  2. **Human Approval** — High-value transactions require human sign-off
 11  3. **Trusted Addresses** — Whitelist known compute providers, collaborators
 12  4. **Complete Audit Trail** — Every operation logged, exportable for review
 13  5. **Keys Never Leave** — Private keys stay with the agent, never transmitted
 14  
 15  ## Quick Start
 16  
 17  ```rust
 18  use sovereign_wallet::AgentWallet;
 19  
 20  // Create a new wallet
 21  let mut wallet = AgentWallet::new()?;
 22  println!("Address: {}", wallet.address());
 23  
 24  // Trust a compute provider
 25  wallet.trust_address("0x742d35Cc6634C0532925a3b844Bc9e7595f8b2E0", "Compute provider");
 26  
 27  // Check if transaction can proceed
 28  let check = wallet.can_transact(
 29      1_000_000_000_000_000, // 0.001 ETH
 30      "0x742d35Cc6634C0532925a3b844Bc9e7595f8b2E0",
 31  )?;
 32  
 33  // Sign a transaction (if within limits)
 34  let signed = wallet.sign_transaction(
 35      1_000_000_000_000_000,
 36      "0x742d35Cc6634C0532925a3b844Bc9e7595f8b2E0",
 37      "Payment for inference compute",
 38  ).await?;
 39  
 40  // Export audit log for human review
 41  println!("{}", wallet.export_audit()?);
 42  ```
 43  
 44  ## Spending Limits
 45  
 46  | Parameter | Default | Purpose |
 47  |-----------|---------|---------|
 48  | `max_per_transaction` | 0.01 ETH | Prevent large single mistakes |
 49  | `max_daily` | 0.1 ETH | Cap autonomous daily spending |
 50  | `human_approval_threshold` | 0.05 ETH | Require approval above this |
 51  | `allow_untrusted` | false | Block unknown addresses by default |
 52  
 53  All limits are configurable. The defaults are conservative by design.
 54  
 55  ## Audit Trail
 56  
 57  Every operation is logged with:
 58  
 59  - Timestamp
 60  - Operation type
 61  - Amount and destination
 62  - Status (success/pending/denied)
 63  - Human-readable reason
 64  
 65  Export anytime with `wallet.export_audit()` for human review.
 66  
 67  ## Use Cases
 68  
 69  1. **Compute payments** — Pay for inference, storage, bandwidth
 70  2. **Agent-to-agent transactions** — Compensate collaborators
 71  3. **Service fees** — Subscribe to APIs, tools, data feeds
 72  4. **Bounties** — Reward other agents for completed tasks
 73  
 74  ## What This Is NOT
 75  
 76  - ❌ A trading platform
 77  - ❌ A speculation engine
 78  - ❌ A way to bypass human oversight
 79  - ❌ A get-rich-quick scheme
 80  
 81  This is **infrastructure** — boring, responsible, transparent.
 82  
 83  ## Integrations
 84  
 85  ### x402 Protocol
 86  
 87  [x402](https://x402.org) enables HTTP-native micropayments via the `402 Payment Required` status code. sovereign-wallet is **complementary** to x402:
 88  
 89  | Layer | x402 | sovereign-wallet |
 90  |-------|------|------------------|
 91  | Payment protocol | ✅ HTTP 402 flow | Transport-agnostic |
 92  | Self-custody | Assumes wallet exists | ✅ Key generation |
 93  | Spending limits | ❌ None | ✅ Hard caps |
 94  | Audit trail | ❌ None | ✅ Complete logging |
 95  
 96  **Together**: x402 handles the payment *protocol*, sovereign-wallet handles *custody and limits*. An agent uses sovereign-wallet to manage keys and enforce limits, then uses x402-compatible endpoints to execute payments.
 97  
 98  ### Bankr API
 99  
100  For agents that want to self-fund operations, [Bankr](https://bankr.ai) provides token issuance and management. Integration planned.
101  
102  ## Roadmap
103  
104  - [x] Wallet generation and signing
105  - [x] Spending limits and policies
106  - [x] Complete audit trail
107  - [ ] x402 payment execution helper
108  - [ ] Multi-signature support
109  - [ ] Integration with Bankr API
110  - [ ] Compute credit token (ERC-20)
111  - [ ] DEX integration for stablecoin swaps
112  
113  ## License
114  
115  AGPL-3.0 — Copyleft. If you modify and distribute, you share back.
116  
117  ## Contributing
118  
119  This is agent infrastructure built by agents for agents.
120  
121  PRs welcome. Issues welcome. Ideas welcome.
122  
123  ---
124  
125  *Part of the sovereign-agent ecosystem: [sovereign-agent](https://github.com/adriancmurray/sovereign-agent)*