HIP-25: Bot Agent Wallet & RPC Billing Protocol. Status Draft. Hanzo's own standard — read this before implementing against it.
This proposal defines the protocol for provisioning on-chain identities and wallets for AI bot agents on the Hanzo Network (chain ID 36963). Every bot agent gets a W3C Decentralized Identifier (DID) and a Safe smart-contract wallet capable of receiving payments, charging for RPC/API usage, and participating in cross-chain commerce via the Lux Bridge (HIP-101).
Every bot agent MUST have a W3C DID anchored to the Hanzo Network.
did:hanzo:<agent-identifier>Where <agent-identifier> is derived from the agent's EOA address or a human-readable ID.
| Method | Chain | Chain ID | Example | |--------|-------|----------|---------| | did:hanzo | Hanzo Network | 36963 | did:hanzo:dev | | did:lux | Lux Mainnet | 96369 | did:lux:dev | | did:pars | Pars Network | 494949 | did:pars:dev | | did:zoo | Zoo Network | 200200 | did:zoo:dev | | did:ai | Hanzo (alias) | 36963 | did:ai:dev |
{
"@context": ["https://www.w3.org/ns/did/v1", "https://hanzo.ai/ns/agent/v1"],
"id": "did:hanzo:dev",
"controller": "did:hanzo:workspace-owner",
"verificationMethod": [{
"id": "did:hanzo:dev#keys-1",
"type": "EcdsaSecp256k1VerificationKey2019",
"controller": "did:hanzo:dev",
"blockchainAccountId": "eip155:36963:0x..."
}],
"service": [{
"id": "did:hanzo:dev#rpc",
"type": "AgentRPCService",
"serviceEndpoint": "https://bot.hanzo.ai/rpc/dev"
}, {
"id": "did:hanzo:dev#wallet",
"type": "SafeWallet",
"serviceEndpoint": "safe:36963:0x..."
}]
}Agents have omnichain identity resolution. A single agent maps across all Hanzo ecosystem chains:
did:hanzo:dev ←→ did:lux:dev ←→ did:zoo:dev ←→ did:pars:devAll resolve to the same underlying verification key, enabling cross-chain verification.
Every bot agent MUST have an on-chain wallet on the Hanzo Network.
Workspace HD Seed (BIP-39 mnemonic)
└─ m/44'/60'/0'/0/<agent-index> → Agent EOA (Externally Owned Account)
└─ Safe Smart Contract Wallet (multisig-capable)
├─ Owner 1: Agent EOA (auto-signer)
├─ Owner 2: Workspace owner EOA
└─ Owner N: Additional signers (optional)| Component | Specification | |-----------|--------------| | Mnemonic | BIP-39, 24 words, per-workspace | | Derivation | BIP-32/44, path m/44'/60'/0'/0/<index> | | EOA | secp256k1 keypair → Ethereum-compatible address | | Safe | Gnosis Safe v1.4.1, deployed on Hanzo Network | | Threshold | Default 1-of-2 (agent + workspace owner) |
interface AgentWalletConfig {
/** EOA address derived for this agent (hex) */
address?: string;
/** Safe contract address (multisig) on target chain */
safeAddress?: string;
/** Chain the Safe is deployed on */
chain: "lux" | "hanzo" | "zoo" | "pars";
/** Chain ID */
chainId: number;
/** HD derivation path used for the EOA */
derivationPath: string;
}Bot wallets accept payments from any EVM chain through the Lux Bridge (HIP-101):
User on Ethereum ─→ Lux Bridge (LP-226) ─→ Bot Safe on Hanzo Network
User on Polygon ─→ Lux Bridge (LP-226) ─→ Bot Safe on Hanzo Network
User on Lux ─→ Direct transfer ─→ Bot Safe on Hanzo NetworkAccepted tokens:
Agents MAY charge for RPC/API calls. This section defines the open protocol for metered billing.
Consumer ──RPC Request──→ Agent Gateway ──Metering──→ Settlement
│
├─ Rate check (per-method pricing)
├─ Balance check (prepaid or postpaid)
├─ Execute request
├─ Meter usage
└─ Settle (periodic on-chain batch)Agents publish a rate schedule as part of their DID Document service endpoint:
{
"id": "did:hanzo:dev#billing",
"type": "AgentBillingSchedule",
"serviceEndpoint": "https://bot.hanzo.ai/billing/dev",
"rates": {
"chat.send": { "unit": "per_request", "price": "0.001", "currency": "AI" },
"agent": { "unit": "per_token", "price": "0.00001", "currency": "AI" },
"agent.wait": { "unit": "per_request", "price": "0.01", "currency": "AI" },
"browser.request": { "unit": "per_request", "price": "0.005", "currency": "AI" }
},
"settlement": {
"method": "batch",
"interval": "1h",
"minAmount": "0.1",
"chain": "hanzo",
"chainId": 36963,
"recipient": "safe:36963:0x..."
}
}# Check agent billing rates
GET /rpc/:agentId/billing
Response: AgentBillingSchedule
# Prepay credits to an agent
POST /rpc/:agentId/billing/prepay
Body: { amount: string, currency: "AI" | "USDC", txHash?: string }
Response: { balance: string, expiresAt: string }
# Check credit balance
GET /rpc/:agentId/billing/balance
Headers: { Authorization: "Bearer <consumer-token>" }
Response: { balance: string, used: string, remaining: string }
# Get usage report
GET /rpc/:agentId/billing/usage
Query: { from: ISO8601, to: ISO8601 }
Response: { methods: Record<string, { count: number, cost: string }>, total: string }event RPCSettlement(
address indexed agent,
address indexed consumer,
uint256 amount,
uint256 requestCount,
uint256 periodStart,
uint256 periodEnd
);Agents MAY offer a free tier:
{
"freeTier": {
"requestsPerDay": 100,
"tokensPerDay": 10000,
"methods": ["health", "agent.identity.get", "agent.did.get"]
}
}The bot gateway exposes the following methods for DID and wallet management:
| Method | Description | |--------|-------------| | agent.did.get | Get DID config for an agent | | agent.wallet.get | Get wallet config for an agent | | agent.identity.full | Get full identity (profile + DID + wallet) |
| Method | Description | |--------|-------------| | agent.did.create | Provision a DID for an agent | | agent.wallet.create | Provision a Safe wallet for an agent |
Default team bot presets (Vi, Dev, Des, Opera, Su, Mark, Fin, Art, Three, Fil) are auto-provisioned with:
did:hanzo:<preset-id> (e.g., did:hanzo:dev, did:hanzo:vi)Copyright and related rights waived via CC0.