Agent Wallet Session
An Agent Wallet session is the active wallet context used by the AI Agent through the ukey wallet CLI. In the current CLI flow, this is exposed through App Transfer or App Bot Wallet login.
What It Unlocks
Once the session is active, the agent can use both read-only and write actions within the same wallet context:
| Capability | Example |
|---|---|
| Wallet state | ukey wallet balance --chain eth |
| Receiving address | ukey wallet get-address |
| History | ukey wallet history --chain eth --detail |
| Market context | ukey wallet token trending --chain sol |
| Swap preparation | ukey wallet swap quote --chain eth --from ETH --to USDC --amount 1 |
| Security checks | ukey wallet security audit --chain eth --token 0x... |
This is also why users do not need to paste private keys to the agent or repeat their address in every prompt. The agent should read the active session and explain which wallet is currently in use.
Login
ukey wallet auth login --app-transfer
UKey Wallet GUI provides the payload. The CLI imports the session into the local UKey Wallet CLI vault and relies on operating-system credential storage to protect sensitive material.
If an automation environment already has the payload, it can be passed explicitly:
ukey wallet auth login --app-transfer --payload <json-or-base64-json>
Status
Every operation flow should begin by checking auth status:
ukey wallet auth status
The current schema returns fields such as:
| Field | Meaning |
|---|---|
authStatus | authenticated or unauthenticated |
loginMethod | app_transfer or hardware |
walletKind | hd for App Transfer sessions, hw for hardware sessions |
displayAddress | The active wallet address shown to the user |
storageBackend | The system credential store used by the CLI |
Lifecycle
| Phase | Agent behavior |
|---|---|
| Before any operation | Run ukey wallet auth status and clearly report an unauthenticated state |
| Before read-only actions | Reuse the active address and chain defaults; only ask if chain or token context is missing |
| Before fund movement | Show the active address, chain, amount, recipient, fee or risk status, then ask for confirmation |
| After a session change | Run ukey wallet auth status again and do not rely on the previous address assumption |
| After logout | Stop using the previous wallet context immediately |
Logout
ukey wallet auth logout
The agent should only call logout when the user explicitly asks to end the current session.