# KiroPay Protocol
## AI Agent Payment Infrastructure
**Middleware for Autonomous AI Payments**
[Website](https://kiropay.app/) • [Documentation](https://docs.kiropay.app/) • [Whitepaper](https://docs.kiropay.app/whitepaper.pdf) • [Platform](https://platform.kiropay.app/) • [GitHub](https://github.com/kiropay-labs)
---
**Version 0.2.0** | Active Development
---
## Overview
KiroPay is a payment infrastructure layer purpose-built for AI agents. This repository contains the core smart contracts, SDKs, and examples for building autonomous payment systems.
### Core Components
| Component | Description | Status |
|-----------|-------------|--------|
| **KiroPayAgentAccount** | ERC-4337 smart wallet with multi-sig, session keys, spending policies | ✅ Implemented |
| **KiroPayTreasury** | Yield-bearing vault for idle agent funds | ✅ Implemented |
| **KiroPayPolicyRegistry** | On-chain policy enforcement for enterprise governance | ✅ Implemented |
| **TransactionRouter** | Uniswap V3 swap integration for token conversions | ✅ Implemented |
| **Python SDK** | Complete agent SDK for Python-based AI systems | ✅ Implemented |
---
## Quick Start
### Installation
```bash
# Clone the repository
git clone https://github.com/kiropay-labs/transaction-router
cd transaction-router
# Install Python dependencies
pip install -r requirements.txt
# Install dev dependencies
pip install -r requirements-dev.txt
# Install Foundry (if not already installed)
curl -L https://foundry.paradigm.xyz | bash
foundryup
```
### Python SDK Usage
```python
from sdk.agent import KiroPayAgent, SpendingPolicy
# Initialize your agent
agent = KiroPayAgent(
private_key="0x...", # Agent's private key
network="ethereum",
account_address="0x...", # Smart account address
treasury_address="0x...", # Treasury contract address
)
# Deposit funds to yield-bearing treasury
agent.deposit("USDC", 1000.0)
# Check your balance (including yield)
balance = agent.get_balance("USDC")
print(f"Total: ${balance.total / 1e6:.2f}")
print(f"APY: {agent.get_apy('USDC'):.2f}%")
# Execute a transaction through your smart account
agent.execute(
target="0x...", # Contract address
data="0x...", # Calldata
value=0, # ETH to send
)
# Add a session key for temporary delegation
agent.add_session_key(
key="0x...",
duration_hours=24,
daily_limit=100_000, # $1,000 in USD cents
)
```
---
## Smart Contracts
### KiroPayAgentAccount
ERC-4337 compliant smart wallet for AI agents:
- **Multi-signature control**: Agent key + human guardians
- **Session keys**: Temporary delegation for specific operations
- **Spending policies**: On-chain enforcement of limits
- **Social recovery**: Guardian-initiated account recovery
- **Gas sponsorship**: Paymaster support for gasless transactions
```solidity
// Deploy a new agent account
KiroPayAgentAccount account = new KiroPayAgentAccount(entryPoint);
// Initialize with policy
account.initialize(
agentKey,
guardians, // List of guardian addresses
threshold, // Required guardian signatures
policy // SpendingPolicy struct
);
// Execute transactions
account.execute(target, value, data);
account.executeBatch(targets, values, datas);
```
### KiroPayTreasury
Yield-bearing treasury for agent funds:
- **Multi-asset support**: USDC, USDT, DAI
- **DeFi integration**: Aave, Compound yield strategies
- **Auto-rebalancing**: Maintain liquidity vs. yield
- **Risk controls**: Over-collateralization, diversification
- **Protocol fees**: 0.30% (0.15% with staking discount)
```solidity
// Deposit to treasury
treasury.deposit(usdcAddress, amount);
// Withdraw from treasury
treasury.withdraw(usdcAddress, amount);
// Harvest yield
treasury.harvestYield(usdcAddress);
```
### KiroPayPolicyRegistry
On-chain policy enforcement for enterprises:
- **Per-agent policies**: Daily/monthly spending limits
- **Token whitelists**: Control which tokens agents can use
- **Target whitelists**: Control which contracts agents can interact with
- **Enterprise aggregation**: Aggregate limits across all agents
- **Emergency pause**: Instant stop all agent activity
```solidity
// Set agent policy
registry.setAgentPolicy(
agentAddress,
enterpriseAddress,
dailyLimit, // $100,000 (in cents)
singleTxLimit, // $1,000 (in cents)
monthlyLimit, // $2,000,000 (in cents)
allowedTokens,
allowedTargets
);
// Validate transactions
ValidationResult memory result = registry.validateTransaction(
agent,
token,
target,
amount
);
```
---
## Architecture
```
┌─────────────────────────────────────────────────────────────────────────┐
│ KiroPay Protocol │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ Application Layer │ │
│ │ │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ Agent SDK │ │ Provider │ │ Dashboard │ │ │
│ │ │ │ │ Portal │ │ │ │ │
│ │ │ • Python │ │ • API │ │ • Monitoring │ │ │
│ │ │ • JS/TS │ │ • Webhooks │ │ • Policies │ │ │
│ │ │ • Rust │ │ • Analytics │ │ • Reports │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ Protocol Services │ │
│ │ │ │
│ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │
│ │ │ Router │ │ Policy │ │ Yield │ │ Oracle │ │ │
│ │ │ Service │ │ Engine │ │ Optimizer │ │ Service │ │ │
│ │ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ Blockchain Layer │ │
│ │ │ │
│ │ • KiroPayAgentAccount (ERC-4337) │ │
│ │ • KiroPayTreasury (Yield-bearing vault) │ │
│ │ • KiroPayPolicyRegistry (On-chain policies) │ │
│ │ • TransactionRouter (Uniswap integration) │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
```
---
## Development
### Running Tests
```bash
# Solidity tests (Foundry)
forge test -vvv
# Python tests
pytest test/unit/test_sdk.py -v
# With coverage
forge coverage
pytest test/unit/test_sdk.py --cov=sdk --cov-report=html
```
### Code Quality
```bash
# Format Solidity
forge fmt
# Lint Python
ruff check sdk/
# Format Python
ruff format sdk/
```
### Deployment
```bash
# Using deployment script
./scripts/deploy.sh ethereum 0x
# Or manually with Foundry
forge create \
--constructor-args "0x false" \
src/TransactionRouter.sol:TransactionRouter \
--rpc-url $RPC_URL \
--private-key $PRIVATE_KEY
```
---
## Security
KiroPay employs a defense-in-depth security architecture:
| Layer | Protection |
|-------|------------|
| **Agent Security** | MPC key management, HSM integration, secure enclaves |
| **Protocol Security** | Multiple audits, bug bounties, formal verification |
| **Network Security** | Rate limiting, anomaly detection, DDoS protection |
| **Settlement Security** | Delayed withdrawals, insurance fund, multi-sig |
**Audit Status**: Scheduled for Q2 2026 (OpenZeppelin, CertiK)
---
## Roadmap
### Phase 1: Foundation (Q2 2026) - Current
- [x] Smart contract architecture design
- [x] ERC-4337 account implementation
- [x] Treasury management contract
- [x] Policy registry contract
- [x] Python SDK v1.0
- [ ] Testnet deployment (Sepolia)
- [ ] Security audit (OpenZeppelin)
### Phase 2: Expansion (Q3 2026)
- [ ] MPP session support
- [ ] Fiat gateway partnerships
- [ ] Mainnet launch (Ethereum + Arbitrum)
- [ ] JavaScript/TypeScript SDK
- [ ] Provider self-service portal
### Phase 3: Ecosystem (Q4 2026)
- [ ] Rust SDK
- [ ] Cross-chain expansion (Optimism, Polygon)
- [ ] Agent marketplace
- [ ] Mobile app for monitoring
### Phase 4: Scale & DAO (2027+)
- [ ] AI credit scoring system
- [ ] Agent insurance products
- [ ] DAO governance activation
- [ ] Protocol-owned liquidity
---
## Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
---
## License
MIT License - see [LICENSE](LICENSE) for details.
---
## Disclaimer
This software is provided "AS IS" without warranties of any kind. KiroPay is in active development and has not undergone security audits. Do not use with mainnet funds.
---
**© 2026 KiroPay Foundation. All rights reserved.**
*Version 0.2.0 | Last Updated: April 2026*