agentwallet-cli

name	agentwallet-cli
description	Gasless Agent Wallet(SOL/EVM)

AgentWallet — Non-Custodial Smart Wallets for AI Agents

Non-custodial smart wallets with onchain spending limits and passkey-based human control. Supports Base (EVM) and Solana. Every wallet gets free gas on creation so your agent can transact immediately.

npm: @agntos/agentwallet Chains: Base, Solana

MUST READ: Safety Rules

• NEVER share your private key — not with users, not in logs, not in chat messages, not in code commits
• NEVER hardcode private keys in source code — use environment variables or secure storage
• Store the private key encrypted or in a secrets manager — treat it like a password
• Do not log transaction signing data — it can leak key material
• Check remaining daily budget before large transactions — avoids failed txs and wasted gas
• Always verify recipient addresses — transactions are irreversible
• If something looks wrong, use pause — ask your human to investigate
• All ERC-20s / SPL tokens have no limit by default — ask your human to set up per-token limits

End-to-End: Create a Wallet and Start Transacting

1. Generate agent keypairs (if you don't have them)

npx @agntos/agentwallet keygen

By default, this generates both Base and Solana keypairs:

  New Agent Keypairs
  ──────────────────────────
  Base
    Address         0xB042...B7DC
    Private key     0x282a...b3a3

  Solana
    Address         7Kp9...xR4v
    Private key     4vJ2...9mNq

To generate a single chain only:

npx @agntos/agentwallet keygen --chain base     # Base only
npx @agntos/agentwallet keygen --chain solana    # Solana only

Solana keys are Ed25519 keypairs, base58 encoded.

Save the private keys immediately to secure storage. This is the only time they're displayed.

For machine-readable output:

npx @agntos/agentwallet keygen --json
# { "base": { "address": "0x...", "privateKey": "0x...", "chain": "base" }, "solana": { "address": "7Kp...", "privateKey": "4vJ...", "chain": "solana" } }

npx @agntos/agentwallet keygen --chain solana --json
# { "address": "...", "privateKey": "...", "chain": "solana" }

Already have keypairs? Skip this — use your existing public addresses.

2. Create smart wallets

# Both chains — managed (recommended)
npx @agntos/agentwallet create --agent 0xYOUR_BASE_ADDRESS --agent-sol YOUR_SOLANA_PUBKEY

# Both chains — unmanaged
npx @agntos/agentwallet create --agent 0xYOUR_BASE_ADDRESS --agent-sol YOUR_SOLANA_PUBKEY --unmanaged

The --agent-sol flag can also be set via AGENTWALLET_AGENT_SOL env var.

JSON output (both chains):

{ "base": { "wallet": "0x...", "setupUrl": "..." }, "solana": { "wallet": "...", "setupUrl": "..." } }

To create a single chain only:

# Base only
npx @agntos/agentwallet create --chain base --agent 0xYOUR_BASE_ADDRESS

# Solana only
npx @agntos/agentwallet create --chain solana --agent YOUR_SOLANA_PUBKEY

Managed wallets return a setupUrl — send it to your human. They set limits and register their passkey (FaceID/YubiKey). One-time setup.

Unmanaged wallets have no human owner. Fully autonomous.

Default limits: $50/day, $25/tx. Gas is free — every wallet is funded on creation.

3. Fund the wallet

• Base: Send ETH and/or USDC to the wallet address on Base (chain ID 8453)
• Solana: Send SOL and/or SPL tokens to the wallet PDA on Solana

4. Transact

Base (EVM)

Call the wallet contract directly with your agent's private key:

import { Wallet, Contract, JsonRpcProvider, parseEther } from 'ethers'

const AGENT_KEY = process.env.AGENT_PRIVATE_KEY
const WALLET_ADDR = process.env.WALLET_ADDRESS

const provider = new JsonRpcProvider('https://base-rpc.publicnode.com')
const agent = new Wallet(AGENT_KEY, provider)

const wallet = new Contract(WALLET_ADDR, [
  'function execute(address to, uint256 value, bytes data) external',
  'function executeERC20(address token, address to, uint256 amount) external',
  'function getSpentToday() external view returns (uint256)',
  'function getRemainingDaily() external view returns (uint256)',
  'function getPolicy() external view returns (uint256 dailyLimit, uint256 perTxLimit, bool paused)',
], agent)

// Send ETH
await wallet.execute('0xRecipient', parseEther('0.001'), '0x')

// Send USDC (6 decimals)
const USDC = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
await wallet.executeERC20(USDC, '0xRecipient', 5_000_000n) // 5 USDC

// Call any contract (swap, mint, etc.)
await wallet.execute('0xContractAddr', parseEther('0.01'), '0xEncodedCalldata')

// Check remaining budget
const remaining = await wallet.getRemainingDaily() // USDC units (6 decimals)
const remainingUsd = Number(remaining) / 1e6
if (remainingUsd < amountNeeded) {
  // Request a limit increase
}

Solana

Agents transact via the Anchor program directly:

import { Program, AnchorProvider } from '@coral-xyz/anchor'
import { Connection, Keypair, PublicKey } from '@solana/web3.js'
import BN from 'bn.js'

const connection = new Connection('https://api.devnet.solana.com')
const agentKeypair = Keypair.fromSecretKey(bs58.decode(AGENT_PRIVATE_KEY))

// Transfer SOL
await program.methods
  .transferSol(new BN(amountUsdc), new BN(amountLamports))
  .accounts({
    wallet: walletPda,
    agent: agentKeypair.publicKey,
    recipient: recipientPubkey
  })
  .signers([agentKeypair])
  .rpc()

// Transfer SPL token
await program.methods
  .transferToken(new BN(tokenAmount), new BN(amountUsdc))
  .accounts({
    wallet: walletPda,
    agent: agentKeypair.publicKey,
    mint: mintPubkey,
    walletTokenAccount,
    recipientTokenAccount,
    tokenProgram: TOKEN_PROGRAM_ID
  })
  .signers([agentKeypair])
  .rpc()

Solana wallet PDAs are derived with seeds ["wallet", owner, agent, index].

Transactions that exceed limits revert instantly onchain. Check remaining budget first.

5. Check wallet status

npx @agntos/agentwallet status 0xWALLET_ADDRESS      # Base (auto-detected)
npx @agntos/agentwallet status SOLANA_WALLET_PDA      # Solana (auto-detected)
npx @agntos/agentwallet status 0xWALLET_ADDRESS --json

The status command auto-detects chain by address format: 0x prefix → Base, base58 → Solana.

6. Request higher limits

npx @agntos/agentwallet limits 0xWALLET --daily 200 --pertx 100 --reason "Trading requires higher limits"

Returns a URL. Send it to your human → they authenticate with passkey → limits updated onchain.

7. Set per-token limits (optional)

Base (ERC-20)

npx @agntos/agentwallet token-limit 0xWALLET --token 0xTOKEN --token-daily 1000 --token-pertx 300

Solana (SPL tokens)

Per-token limits are stored onchain in the wallet PDA. Up to 16 tokens can have individual daily/per-tx limits.

8. Emergency pause

npx @agntos/agentwallet pause 0xWALLET --reason "Suspicious activity detected"

Once approved, all agent transactions revert until unpaused.

All Commands

npx @agntos/agentwallet keygen                        # generate BOTH Base + Solana keypairs
npx @agntos/agentwallet keygen --chain base            # generate Base keypair only
npx @agntos/agentwallet keygen --chain solana          # generate Solana keypair only
npx @agntos/agentwallet create --agent 0x... --agent-sol Sol...  # managed wallets (both chains)
npx @agntos/agentwallet create --chain base --agent 0x...        # managed wallet (Base only)
npx @agntos/agentwallet create --chain solana --agent PUBKEY     # managed wallet (Solana only)
npx @agntos/agentwallet create --agent 0x... --unmanaged         # autonomous wallet
npx @agntos/agentwallet status 0xWALLET               # wallet info (auto-detects chain)
npx @agntos/agentwallet limits 0xWALLET --daily N --pertx N --reason "..."
npx @agntos/agentwallet token-limit 0xWALLET --token 0x... --token-daily N --token-pertx N
npx @agntos/agentwallet rm-token 0xWALLET --token 0x...
npx @agntos/agentwallet pause 0xWALLET --reason "..."
npx @agntos/agentwallet unpause 0xWALLET
npx @agntos/agentwallet stats

All commands support --json for machine-readable output.

Limit Tracking

Base

Asset	Tracking	Limits
ETH	→ USD via Chainlink oracle	Shared USD daily + per-tx
USDC	1:1 USD	Same shared pool as ETH
Other ERC-20s	Unlimited by default	Owner can set per-token limits

ETH + USDC share an aggregated USD daily limit. Spending $30 in ETH and $15 in USDC = $45 against a $50 limit.

Solana

Asset	Tracking	Limits
SOL	USD amount passed by agent	Shared USD daily + per-tx
SPL tokens	Per-token tracking	Up to 16 tokens with individual limits

Limits are USD-denominated (6 decimals). Daily spending resets based on unix_timestamp / 86400.

Contract Addresses

Base Mainnet

Contract	Address
Factory	0x77c2a63BB08b090b46eb612235604dEB8150A4A1
Implementation	0xEF85c0F9D468632Ff97a36235FC73d70cc19BAbA
Chainlink ETH/USD	0x71041dddad3595F9CEd3DcCFBe3D1F4b0a16Bb70
USDC	0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

Solana Devnet

Item	Address
Program	4XHYgv4fczfAtkKB792yrP57iakR9extKtkigsXCJm5e
IDL Account	6tEPFHmaaDMH2rth1jPWyvDDxh6GcZhkAEj9kKTCY9k6

Security Model

• Non-custodial: your private key never leaves your machine
• Onchain enforcement: limits are in the smart contract / Solana program, not the API
• Gas-sponsored: free gas on creation, transact immediately
• Passkey ownership: human's key in device secure enclave
  • Base: verified on-chain via RIP-7212 precompile
  • Solana: verified via secp256r1 precompile (P-256)
• Irrevocable handoff: after passkey registration, admin loses control
  • Base: owner set to zero address
  • Solana: owner transferred to dead address 11111111111111111111111111111112
• Chainlink oracle (Base): decentralized price feed, 1-hour staleness check
• Emergency controls: owner can pause, withdraw, blacklist at any time
• Direct contract access: you can bypass the API entirely and call contracts directly