Gasless Agent Wallet (SOL/EVM)

intent

build non-custodial smart wallets for AI agents on Base (EVM) and Solana that enforce onchain spending limits, support passkey-based human override, and come pre-funded with gas. use this when your agent needs to transact autonomously without custody risk, with humans able to pause, adjust limits, or reclaim funds at any time. works for both managed wallets (with human owner) and fully autonomous agents.

inputs

external connections:

• Base RPC endpoint: defaults to https://base-rpc.publicnode.com, override via BASE_RPC_URL env var
• Solana RPC endpoint: defaults to https://api.devnet.solana.com, override via SOLANA_RPC_URL env var
• Chainlink ETH/USD oracle (Base mainnet only): 0x71041dddad3595F9CEd3DcCFBe3D1F4b0a16Bb70, used for limit tracking (1-hour staleness tolerance)

required context:

• agent private key (Base): hex string, 32 bytes, stored in AGENT_PRIVATE_KEY env var. never log or commit this.
• agent private key (Solana): base58-encoded Ed25519 key, stored in AGENT_PRIVATE_KEY_SOL env var
• wallet address (Base): 0x-prefixed, 42 chars
• wallet PDA (Solana): base58 public key derived from seeds ["wallet", owner, agent, index]
• human's passkey (for managed wallets): FaceID, YubiKey, or equivalent, registered during one-time setup via setupUrl

optional context:

• per-token limits (Base): up to any number of ERC-20 contracts with individual daily/per-tx caps
• per-token limits (Solana): up to 16 SPL token mints with individual limits

edge cases and limits:

• rate limits: RPC nodes enforce request throttling (varies by provider); batch calls where possible, add exponential backoff on 429 responses
• auth expiry: passkey registration is one-time; if human loses device, limits/pause cannot be updated without wallet recovery (owner-initiated)
• empty result sets: status command returns zero balances if wallet not yet funded; transactions revert (not fail silently) if limit exceeded
• network timeouts: set RPC timeout to 30 seconds; retry with exponential backoff (2s, 4s, 8s max)
• Solana PDAs: derivation requires both owner and agent public keys; incorrect seeds return "PDA not found" error

procedure

step 1: generate agent keypairs

inputs: optional --chain flag (base, solana, or omit for both)

run the keygen command to create one or both keypairs:

npx @agntos/agentwallet keygen
# outputs both Base (0x-prefixed) and Solana (base58) keypairs, one-time display only

npx @agntos/agentwallet keygen --chain base
# outputs Base keypair only

npx @agntos/agentwallet keygen --chain solana
# outputs Solana keypair only

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

outputs: agent address (for Base: 0x-prefixed, 42 chars; for Solana: base58, 44 chars) and private key (hex for Base, base58 for Solana).

critical: save private keys to secure storage (secrets manager, encrypted file, env var) immediately. this is the only time they display.

step 2: create smart wallets

inputs: agent public address (Base or Solana or both), optional --unmanaged flag, optional --chain flag

create wallets for your agent:

# both chains, managed (human can set limits and passkey)
npx @agntos/agentwallet create --agent 0xYOUR_BASE_ADDRESS --agent-sol YOUR_SOLANA_PUBKEY

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

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

# both chains, autonomous (no human control)
npx @agntos/agentwallet create --agent 0xYOUR_BASE_ADDRESS --agent-sol YOUR_SOLANA_PUBKEY --unmanaged

# JSON output for parsing
npx @agntos/agentwallet create --agent 0x... --agent-sol ... --json

env var override: --agent-sol can also be set via AGENTWALLET_AGENT_SOL.

outputs: wallet address (Base: 0x-prefixed; Solana: base58 PDA), and setupUrl for managed wallets.

default limits: $50/day, $25/per-tx. ETH and USDC share an aggregated USD pool. ERC-20s and SPL tokens unlimited by default.

free gas: every wallet is pre-funded on creation; agent can transact immediately.

step 3: fund the wallet

inputs: wallet address, amount in native asset or ERC-20/SPL token

send funds to the created wallet:

• Base: send ETH and/or USDC to the wallet address on chain ID 8453
• Solana: send SOL and/or SPL tokens to the wallet PDA on Solana devnet (or mainnet if applicable)

outputs: none (confirmed via block explorer or status command)

step 4: check remaining budget before transacting

inputs: wallet address, optional --json flag

npx @agntos/agentwallet status 0xWALLET_ADDRESS
# auto-detects chain by address format (0x = Base, base58 = Solana)

npx @agntos/agentwallet status 0xWALLET_ADDRESS --json
# machine-readable: { "wallet": "0x...", "chain": "base", "dailyLimit": "50000000", "perTxLimit": "25000000", "spent": "15000000", "remaining": "35000000", "paused": false, ... }

outputs: current daily/per-tx limits, amount spent today (in USD, 6 decimals), amount remaining, pause status, list of per-token limits (if any).

critical: always check remaining budget before attempting a large transaction. transactions exceeding limits revert onchain and waste gas (even though gas is free, execution time is not).

step 5a: transact on Base (EVM)

inputs: agent private key, wallet contract address, recipient address, amount or encoded calldata

use ethers.js (or equivalent) to call the wallet contract:

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 getRemainingDaily() external view returns (uint256)',
  'function getPolicy() external view returns (uint256 dailyLimit, uint256 perTxLimit, bool paused)',
], agent)

// send native 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, LP, etc.)
await wallet.execute('0xDexAddr', parseEther('0.01'), '0xSwapCalldata')

// query remaining budget before large tx
const remaining = await wallet.getRemainingDaily()
const remainingUsd = Number(remaining) / 1e6
if (remainingUsd < 10) {
  console.error('insufficient budget, request limit increase')
}

outputs: transaction hash, confirmed onchain. if limit exceeded, transaction reverts with no state change.

edge case: if agent is not the wallet's admin, calls will revert. verify agent address matches wallet creation input.

step 5b: transact on Solana

inputs: agent keypair (Ed25519), wallet PDA, recipient public key, amount in lamports/smallest token unit, and USD amount spent

use Anchor to call the wallet program:

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

const connection = new Connection('https://api.devnet.solana.com')
const agentKeypair = Keypair.fromSecretKey(bs58.decode(process.env.AGENT_PRIVATE_KEY_SOL))
const walletPda = new PublicKey('...')
const recipientPubkey = new PublicKey('...')

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

// transfer SPL token
const mint = new PublicKey('...')
const walletTokenAccount = await getAssociatedTokenAddress(mint, walletPda, true)
const recipientTokenAccount = await getAssociatedTokenAddress(mint, recipientPubkey)

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

outputs: transaction signature, confirmed onchain. if limit exceeded, instruction fails atomically.

edge case: SPL token accounts (ATA) must exist before transfer; transferToken does not create them. agent must have created or funded ATA in advance.

step 6: set or request higher limits

inputs: wallet address, new daily and/or per-tx limit amounts, optional reason string

request a limit increase (managed wallets only):

npx @agntos/agentwallet limits 0xWALLET --daily 200 --pertx 100 --reason "high-volume trading"

outputs: approval URL. send to human owner, they authenticate with passkey, limits update onchain.

edge case: unmanaged wallets cannot request limits; owner-initiated pause/withdrawal is the only override.

step 7: set per-token limits (optional)

inputs: wallet address, token contract address (Base) or mint (Solana), daily and per-tx caps in smallest units

set individual caps for specific tokens:

# Base ERC-20
npx @agntos/agentwallet token-limit 0xWALLET --token 0xTOKEN_ADDR --token-daily 1000 --token-pertx 300

# Solana SPL
npx @agntos/agentwallet token-limit WALLET_PDA --token MINT_PUBKEY --token-daily 1000 --token-pertx 300

outputs: confirmation, limit stored onchain.

constraints: Base allows unlimited tokens; Solana supports up to 16 tokens with individual limits.

step 8: emergency pause

inputs: wallet address, optional reason string

pause all agent transactions immediately:

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

outputs: approval URL (managed wallets) or immediate pause (unmanaged). once paused, all agent-signed transactions revert.

unpause with:

npx @agntos/agentwallet unpause 0xWALLET

decision points

if creating a managed wallet (human control):

• output includes setupUrl. send to human to register passkey and set limits. once passkey is registered, admin (you) loses control permanently.
• human can later request new limits, pause, or unpause via passkey authentication.

else if creating unmanaged wallet (fully autonomous):

• no setupUrl returned. wallet operates under default limits and only emergency pause (admin-initiated) is available.
• no human can modify limits onchain; only admin can withdraw or pause.

if remaining daily budget is zero or near zero:

• agent cannot transact. request a limit increase (managed) or pause and manually withdraw funds to refund (unmanaged/admin).
• do not attempt transactions; they will revert, wasting execution cycles.

if Solana SPL token transfer and recipient ATA does not exist:

• call fails. create ATA first via getAssociatedTokenAddress(..., false) and fund it, or use a wallet that auto-creates ATAs.

if Chainlink oracle (Base) is stale (>1 hour):

• limit tracking may be inaccurate. pause wallet and investigate oracle status.

if RPC returns 429 (rate limited):

• backoff exponentially (2s, 4s, 8s). switch to backup RPC if primary is consistently throttled.

if wallet address format unrecognized in status command:

• command auto-detects by prefix (0x = Base, base58 = Solana). if detection fails, explicitly pass --chain base or --chain solana.

if human loses device (passkey gone):

• only admin can pause or withdraw. passkey registration is irrevocable, so new passkey cannot be registered. wallet is frozen unless admin resets it (recovery process not detailed here).

output contract

keygen:

• text output: agent address (public key) and private key (one-time display)
• JSON: { "base": { "address": "0x...", "privateKey": "0x...", "chain": "base" }, "solana": { ... } }
• private key must be persisted by caller to secure storage

create:

• text output: wallet address and setupUrl (if managed)
• JSON: { "base": { "wallet": "0x...", "setupUrl": "..." }, "solana": { "wallet": "...", "setupUrl": "..." } }
• wallet addresses are deterministic; re-running with same agent produces same address

status:

• text output: formatted wallet info (limits, spent, remaining, paused status, token limits)
• JSON: { "wallet": "0x...", "chain": "base", "dailyLimit": "50000000", "perTxLimit": "25000000", "spent": "15000000", "remaining": "35000000", "paused": false, "tokenLimits": [ ... ] }
• amounts are in smallest units (6 decimals for USD, 18 for ETH, per-token decimals for ERC-20/SPL)

limits / pause / token-limit:

• text output: confirmation message and (if managed) approval URL
• JSON: { "status": "pending" | "approved", "approvalUrl": "..." }

Base contract addresses (mainnet):

• Factory: 0x77c2a63BB08b090b46eb612235604dEB8150A4A1
• Implementation: 0xEF85c0F9D468632Ff97a36235FC73d70cc19BAbA
• Chainlink ETH/USD: 0x71041dddad3595F9CEd3DcCFBe3D1F4b0a16Bb70
• USDC: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

Solana program addresses (devnet):

• Program: 4XHYgv4fczfAtkKB792yrP57iakR9extKtkigsXCJm5e
• IDL Account: 6tEPFHmaaDMH2rth1jPWyvDDxh6GcZhkAEj9kKTCY9k6

outcome signal

keygen: user has private keys stored in secure location (env var, secrets manager, encrypted file) and can reference them for wallet creation.

create: wallet address appears on Base (Etherscan) or Solana (Solscan), shows zero balance before funding. setup URL (if managed) can be opened by human to register passkey.

fund: wallet balance increases on block explorer after transaction confirms. agent can query via status command.

transact (Base): transaction hash appears on Etherscan, state changes (recipient balance increases or contract action executed). getRemainingDaily() decreases by transaction amount.

transact (Solana): transaction signature appears on Solscan, recipient account balance increases. wallet PDA state updates to reflect new daily spend.

status: command returns non-zero "remaining" value, "paused" is false, and transaction can proceed. if paused or remaining is zero, no further transactions execute.

limits request: human receives email or in-app notification with approval URL. after passkey auth, status command shows new limits onchain.

pause: agent-signed transactions immediately revert with error code. manual inspection shows wallet paused flag is true.

unpause: agent-signed transactions resume execution.

---

npm package: @agntos/agentwallet chains: Base (EVM), Solana (both devnet and mainnet)

security model: non-custodial (your private key never leaves your machine), onchain enforcement (limits are in contract/program, not API), passkey ownership (human's key in device secure enclave, verified onchain via RIP-7212 on Base or secp256r1 on Solana), irrevocable handoff (after passkey registration, admin loses control permanently), Chainlink oracle (Base mainnet only, 1-hour staleness tolerance), emergency controls (admin can pause/withdraw at any time).