SuiAgentWallet

AI Agent wallet powered by Sui blockchain, featuring zkLogin passwordless auth, Deepbook Dex trading, and on-chain delegation-based fund management.

Sui Core Features

• ZkLogin Agent Wallet — Google login, zero private key management
• PTB Execution — Backend tools return PTB → frontend buildTransactionFromPtb builds → zkLogin signing → on-chain submission
• Delegation List — Filtered by current wallet address, live on-chain status refresh

Frontend

Tech stack: React 19 + Vite + Zustand + React Query + i18n (zh-CN / en-US)

Sidebar Navigation

Module	Route	Function
AI Assistant	/home	Multi-turn chat + tool execution + streaming
Sui Wallet	/wallet	Balance, send/receive, transaction history, PTB approval
Delegations	/delegations	On-chain delegation management (create, query, refresh status)
MCP	/mcp	MCP protocol server configuration
Skills	/skills	Agent Skills management
Webhooks	/webhooks	Webhook registration
Channels	/channels	Multi-channel notifications
Settings	/settings	Application settings
Admin	/admin	Admin panel

Backend

Tech stack: FastAPI + SQLModel + APScheduler + 80+ tools + multi-model routing

Sui Tools (tools/sui/)

Tool	Purpose
create_delegation	Build PTB to create delegation (auto-discovers wallet address/coin/network)
list_delegations	List saved delegation records + on-chain status refresh
check_delegation	Query on-chain delegation state (balance, allowance, expiry)
revoke_delegation	Revoke delegation
place_grid_orders	Place grid limit orders on Deepbook (auto-withdraw settled funds)
cancel_order	Cancel order + withdraw returned funds
get_open_orders	Query BM for open/filled orders
get_pool_info	Query Deepbook pool info
withdraw_settled	Withdraw funds from BM
swap	Direct Deepbook token swap
trade_history	On-chain TradeRecord query
guardian	PTB risk assessment

Delegation Contract (contracts/delegation/)

Delegation<T> shared object with physically locked funds.

Write Methods

Method	Caller	Description
create<T>(agent, coin, max_amount, expires_at_ms, clock, ctx)	owner	Create delegation (target restricted to owner)
create_with_targets<T>(agent, coin, max_amount, expires_at_ms, allowed_targets, clock, ctx)	owner	Create delegation with target whitelist
spend<T>(delegation, amount, target, clock, ctx) → Coin<T>	agent	Spend from delegation, atomic within PTB. Enforces: agent identity, not revoked, not expired, target in whitelist, cumulative ≤ cap
spend_and_transfer<T>(delegation, amount, target, clock, ctx)	agent	spend + auto-transfer to sender
deposit<T>(delegation, coin)	owner	Add funds (does not change max_amount)
extend_cap<T>(delegation, new_max, ctx)	owner	Raise max_amount
revoke<T>(delegation, ctx) → Coin<T>	owner	Revoke delegation, return all balance

Read-Only Methods

Method	Description
remaining_balance<T>(delegation) → u64	Current balance
remaining_allowance<T>(delegation) → u64	Remaining allowance (max_amount - spent)
is_active<T>(delegation, clock) → bool	Active check (not revoked + not expired)
owner<T>(delegation) → address	Owner address
agent<T>(delegation) → address	Agent address

Events

Event	Trigger
DelegationCreated	Delegation created
SpendExecuted	Agent spent successfully
DelegationRevoked	Delegation revoked
DelegationToppedUp	Funds deposited

Agent Context

Each chat request includes sui_address + sui_network from the frontend → stored in session metadata → injected into context.extra. Tools read these automatically — the agent never needs to ask for address, network, or coin IDs.

Data Flow

User input → ChatView → runChatStream (with sui_address + network)
  → POST /chat/stream → Agent (QueryEngine)
    → Tool call (create_delegation / place_grid_orders / ...)
    → PTB instructions { instructions: [...] }
  ← Server-Sent Events (SSE)
→ SuiPtbToolCard auto-execute / PTBApprovalDialog manual confirm
  → resolveWalletCoins (coin discovery fallback)
  → buildTransactionFromPtb (PTB → Transaction)
  → zkLogin signing → executeTransactionBlock
  → Parse events → saveOrderRecords / saveDelegationToDb
  → notifyAgentOfPtbResult → Continue conversation

Environment Configuration

Backend .env

Variable	Description	Required
SUIAGENT_ZKLOGIN__ENABLED	Enable zkLogin (true / false)	Yes
SUIAGENT_ZKLOGIN__GOOGLE_CLIENT_ID	Google OAuth Client ID	Yes
SUIAGENT_ZKLOGIN__SALT_MASTER_SEED	64-char hex salt seed	Yes
SUIAGENT_ZKLOGIN__SESSION_TOKEN_SECRET	64-char hex session secret	Yes
SUIAGENT_ZKLOGIN__PROVER_URL	zkLogin prover URL (default: Mysten dev)	Optional
SUIAGENT_ZKLOGIN__PROVER_URL_TESTNET	Per-network override (testnet)	Optional
SUIAGENT_ZKLOGIN__PROVER_URL_MAINNET	Per-network override (mainnet)	Optional
SUIAGENT_ZKLOGIN__PROVER_URL_DEVNET	Per-network override (devnet)	Optional
SUIAGENT_SUI__DELEGATION_PACKAGE_ID	Delegation contract package ID	Yes
DEEPSEEK_API_KEY	DeepSeek API Key	Optional
DATABASE_URL	PostgreSQL URL (defaults to SQLite)	Optional

Full example: backend/.env.example.

Frontend .env

Variable	Description	Required
VITE_API_BASE_URL	Backend API URL	Yes
VITE_GOOGLE_CLIENT_ID	Google OAuth Client ID (same as backend)	Yes
VITE_SUI_RPC_TESTNET	Sui testnet RPC (optional, defaults to public fullnode)	Optional
VITE_SUI_RPC_MAINNET	Sui mainnet RPC (recommend Shinami)	Optional

Full example: frontend/.env.example.

Quick Start

# Backend
cd backend && uv sync && uv run python -m suiagent

# Frontend
cd frontend && npm install && npm run dev

License

Apache License 2.0 — see LICENSE.