💧 Spraay Agent Wallet

Smart contract wallets for AI agents on Base.

Inspired by Abstract Global Wallet (AGW) architecture, adapted for AI agent use cases. Agents can self-provision wallets via the Spraay x402 Gateway and operate autonomously using session keys with spending limits.

Why This Exists

AI agents need wallets. The current options are:

• Phantom Server SDK — Requires approval in their developer program (slow)
• Abstract Global Wallet — Requires browser-based Privy key-sharding (agents don't have browsers)
• Manual EOA creation — No spending limits, no session keys, no safety rails

Spraay Agent Wallet takes the best architectural patterns from Abstract's AGW (factory-deployed smart contract wallets, session keys, batched transactions) and strips out the parts that don't work for non-human actors. The result is a wallet system designed specifically for AI agents:

• One API call to provision a wallet
• Session keys with spending limits and time bounds
• Batch execution for gas-efficient multi-step operations
• Agent metadata for identity and ProofLayer trust scoring
• Deployed on Base — plugs directly into Spraay's 76+ gateway endpoints

Architecture

AI Agent (ElizaOS / LangChain / CrewAI / etc.)
    │
    │  x402 USDC micropayment
    ▼
Spraay Gateway (gateway.spraay.app)
    │
    │  POST /v1/wallet/provision
    ▼
SpraayWalletFactory (Base mainnet)
    │
    │  CREATE2 deploy (EIP-1167 minimal proxy)
    ▼
SpraayAgentWallet (smart contract)
    ├── Owner (EOA — generated or self-custody)
    ├── Session Keys (spending limits, time bounds, target restrictions)
    ├── Batch Execution (multi-call in one tx)
    └── Agent Metadata (agentId, agentType → ProofLayer)

Contracts

Contract	Description
SpraayAgentWallet.sol	Core wallet implementation — execute, batch, session keys, agent metadata
SpraayWalletFactory.sol	Factory for deploying wallets via CREATE2 (EIP-1167 clones)
interfaces/ISpraayAgentWallet.sol	Wallet interface
interfaces/ISpraayWalletFactory.sol	Factory interface

Gateway Endpoints (Category 17)

Endpoint	Method	Price	Description
/v1/wallet/provision	POST	$0.05	Create a new agent wallet
/v1/wallet/session-key	POST	$0.02	Add a session key
/v1/wallet/info/:address	GET	$0.005	Get wallet info
/v1/wallet/revoke-key	POST	$0.02	Revoke a session key
/v1/wallet/predict	GET	Free	Predict wallet address

Quick Start

1. Deploy Contracts

git clone https://github.com/plagtech/spraay-agent-wallet
cd spraay-agent-wallet
npm install
cp .env.example .env
# Add your PRIVATE_KEY and BASESCAN_API_KEY

# Deploy to Base Sepolia (testnet)
npx hardhat run scripts/deploy.ts --network base-sepolia

# Deploy to Base Mainnet
npx hardhat run scripts/deploy.ts --network base

2. SDK Usage (for agent frameworks)

import { SpraayWallet } from 'spraay-agent-wallet';

// Provision a new wallet
const wallet = await SpraayWallet.provision({
  agentId: 'my-trading-agent',
  agentType: 'langchain',
  mode: 'managed',
}, {
  x402PaymentHeader: process.env.X402_HEADER,
});

console.log(`Wallet: ${wallet.address}`);

// Add a session key (1 ETH limit, 24 hours)
const session = await wallet.addSessionKey({
  spendLimitEth: '1.0',
  durationHours: 24,
  allowedTargets: ['0x...SpraayBatchContract'],
});

// Agent can now operate autonomously within limits

3. Direct API Usage

# Provision a wallet
curl -X POST https://gateway.spraay.app/v1/wallet/provision \
  -H "Content-Type: application/json" \
  -H "X-402-Payment: <payment-header>" \
  -d '{
    "agentId": "my-agent-001",
    "agentType": "eliza",
    "mode": "managed"
  }'

# Response:
# {
#   "success": true,
#   "wallet": {
#     "walletAddress": "0x...",
#     "ownerAddress": "0x...",
#     "encryptedKey": "...",
#     "txHash": "0x...",
#     "chainId": 8453
#   }
# }

Session Keys

Session keys are the core feature that makes this work for agents. Instead of giving an agent the master key (dangerous), you give it a session key with:

• Spending limit: Max total ETH/tokens the key can spend
• Time bound: Key expires after a set duration
• Target restrictions: Key can only interact with specific contracts

Master Key (owner)
    │
    ├── Session Key A: 0.5 ETH, 24hrs, [SpraayBatch, MangoSwap]
    ├── Session Key B: 0.1 ETH, 1hr, [RTP endpoints only]
    └── Session Key C: 2.0 ETH, 7days, [any target]

An agent creates its own session keys with appropriate limits for its task, then operates within those bounds. If a session key is compromised, the damage is limited to the spending cap.

How It Compares

Feature	Spraay Agent Wallet	Abstract AGW	Phantom Server SDK
Agent-native	✅	❌ (browser-based)	⚠️ (needs approval)
Session keys	✅	✅	❌
Batch execution	✅	✅	❌
Chain	Base	Abstract L2	Multi-chain
Key custody	Flexible	Privy shards	Phantom servers
Open source	✅ GPL-3.0	✅ GPL-3.0	❌ Proprietary
x402 payment	✅	❌	❌
ProofLayer integration	✅	❌	❌
Approval required	❌	❌	✅

Integration with Spraay Ecosystem

• Spraay Gateway: Wallet endpoints join the existing 76+ paid endpoints
• ProofLayer: Agent metadata feeds into trust scoring (reliability, financial behavior)
• RTP: Robot Task Protocol agents can self-provision wallets for micropayments
• StablePay: Payroll recipients get wallets automatically
• MangoSwap: Agents can swap tokens via their smart contract wallet

Credits

• Architecture inspired by Abstract Global Wallet (Igloo Inc.)
• Smart contract patterns adapted from Clave
• EIP-1167 minimal proxy from OpenZeppelin

License

GPL-3.0 (same as AGW contracts)

---

Spraay 💧 — Multi-chain batch payment protocol
gateway.spraay.app · @Spraay_app · docs.spraay.app