Skip to content

[codex] Improve agent wallet docs #1353

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
blakecduncan merged 7 commits into from
Jun 5, 2026
Merged

[codex] Improve agent wallet docs #1353

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
1c65ec9
Improve agent wallet docs
blakecduncan Jun 5, 2026
d9287e2
Tighten agent wallet docs
blakecduncan Jun 5, 2026
7baabcc
Improve agent wallet docs layout
blakecduncan Jun 5, 2026
1ba8b53
Align agent wallet examples
blakecduncan Jun 5, 2026
9f148d1
Polish agent wallet capability cards
blakecduncan Jun 5, 2026
374030e
Add Solana sponsorship example
blakecduncan Jun 5, 2026
006e818
Merge branch 'main' into codex/improve-agent-wallet-docs
blakecduncan Jun 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
280 changes: 257 additions & 23 deletions content/tutorials/build-with-ai/agent-wallets.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,43 +1,277 @@
---
title: Agent Wallets
description: Give your AI agent a secure wallet it can use from the Alchemy CLI without exposing private keys.
subtitle: Wallets that allow your agent to send tokens, swap, bridge, call contracts and check transaction status.
description: Give an agent an approved Alchemy wallet session for onchain actions through the Alchemy CLI.
subtitle: Use Agent Wallets to send tokens, call contracts, swap, bridge, sponsor gas, and check status from the Alchemy CLI.
slug: docs/agent-wallets
---

Agent Wallets give your AI agent a real onchain wallet it can use with the [Alchemy CLI](docs/alchemy-cli) to perform onchain actions.
Agent Wallets give an agent an approved CLI session for onchain actions. The agent can use wallet-aware Alchemy CLI commands, but it does not receive or handle the wallet private key.

Built with Privy embedded wallets, your agent will never see the wallet's private key. You approve wallet access, and you can revoke it at any time.
The session is approved in the Alchemy Dashboard, expires automatically, and can be revoked from the Dashboard or with `alchemy wallet disconnect`.

## Get Started

Paste this prompt into your AI agent:

```bash
Install the latest Alchemy CLI with `npm i -g @alchemy/cli@latest`, then help me log in and create a wallet.
```

Your agent installs the CLI, authenticates, and connects an Agent Wallet.

## Use cases
## Capabilities

<CardGroup cols={2}>
<Card title="DeFi automation" icon="chart-line">
Check balances, quote and execute swaps, bridge to another chain, and deposit into a protocol — all in a single agent workflow.
<Card title="EVM actions" icon="code">
Send native tokens or ERC-20s, execute contract calls, manage ERC-20 approvals,
swap on EVM mainnets, and bridge between EVM mainnets.
</Card>
<Card title="Onchain development" icon="code">
Fund test wallets, deploy contracts, call contract methods, and automate repetitive dev tasks without leaving the CLI.
<Card title="Solana sends" icon="bolt">
Send SOL or SPL tokens, run dry runs, handle associated token accounts, and use
session signing for supported CLI flows.
</Card>
<Card title="Treasury management" icon="wallet">
Send payments, move assets between wallets, and rebalance across chains as part of operational or finance workflows.
<Card title="Sponsorship" icon="wallet">
Request EVM gas sponsorship or Solana fee sponsorship with a policy ID.
</Card>
<Card title="Multi-chain workflows" icon="arrow-right-arrow-left">
Bridge assets to where they're needed, then act — swap, deposit, or call contracts on the destination chain.
<Card title="Session control" icon="shield">
Approve sessions in the Dashboard, inspect the active session, and revoke
access from the CLI or Dashboard.
</Card>
</CardGroup>

<AccordionGroup>
<Accordion title="Detailed capability reference">
**Chains:** EVM wallet operations run on supported Alchemy wallet networks.
Solana sends run on supported Solana networks. Swaps and bridges are EVM
mainnet-only.

**EVM sends:** `alchemy evm send` supports native token and ERC-20 sends. ENS
recipients work where the selected network/client can resolve them.

**Contract writes:** `alchemy evm contract call` supports state-changing EVM
calls with inline signatures, ABI files, JSON args, and optional ETH value.

**Approvals:** `alchemy evm approve` supports ERC-20 approve, reset, and
revoke flows. Unlimited approvals require confirmation or `--yes`.

**Swaps:** `alchemy evm swap quote` and `alchemy evm swap execute` support
same-chain EVM mainnet swaps with slippage controls.

**Bridges:** `alchemy xchain bridge quote` and `alchemy xchain bridge execute`
support EVM mainnet bridges from `-n, --network` to `--to-network`.

**Status:** `alchemy evm status` checks smart-wallet call IDs and EVM
transaction hashes. `alchemy solana status` checks Solana signatures.
</Accordion>
<Accordion title="Session capabilities and limits">
A session can include `evm.signMessage`, `evm.signTypedData`,
`evm.signAuthorization`, `evm.prepareCalls`, `evm.sendCalls`, and
`solana.signTransaction`.

The session signer does not support direct raw EVM transaction signing. Use
CLI commands that execute through Alchemy smart-wallet calls.

Gas and fee sponsorship policies control transaction fees. They are not
wallet spend limits.
</Accordion>
<Accordion title="Discovery commands">
Use these commands when an agent needs the current wallet contract:

```bash
alchemy --json --no-interactive wallet status --verify
alchemy --json --no-interactive agent-prompt --scope wallet
alchemy evm network list
alchemy solana network list
```

For the latest published CLI surface, use:

```bash
npx -y @alchemy/cli@latest --json --no-interactive agent-prompt --scope wallet
```
</Accordion>
</AccordionGroup>

## Connect a session

Install the CLI, log in, and start a Dashboard approval flow:

```bash
npm i -g @alchemy/cli@latest
alchemy auth
alchemy wallet connect --mode session --instance-name codex-terminal
```

Verify the approved session before running a state-changing workflow:

```bash
alchemy --json --no-interactive wallet status --verify
```

The response includes the active signer, session expiry, chain-specific session metadata, backend status, and enabled signer capabilities.

## Examples

<Tabs>
<Tab title="EVM">
This workflow assumes you already approved a session. It checks funding,
previews a send, broadcasts it, and checks status.

```bash
alchemy --json --no-interactive wallet address
alchemy --json --no-interactive evm data balance <session_evm_address> -n base-mainnet

alchemy --json --no-interactive evm send <recipient> 0.001 \
-n base-mainnet \
--dry-run

alchemy --json --no-interactive evm send <recipient> 0.001 \
-n base-mainnet

alchemy --json --no-interactive evm status <call-id-or-tx-hash> -n base-mainnet
```

For sponsored gas, pass a Gas Manager policy:

```bash
alchemy --json --no-interactive evm send <recipient> 0.001 \
-n base-mainnet \
--gas-sponsored \
--gas-policy-id <gas-policy-id>
```
</Tab>

<Tab title="Solana">
This workflow assumes you already approved a session. It checks funding,
previews a send, broadcasts it, and checks status.

```bash
alchemy --json --no-interactive wallet address
alchemy --json --no-interactive solana rpc getBalance <session_solana_address> -n solana-mainnet

alchemy --json --no-interactive solana send <recipient_pubkey> 0.01 \
-n solana-mainnet \
--dry-run

alchemy --json --no-interactive solana send <recipient_pubkey> 0.01 \
-n solana-mainnet

alchemy --json --no-interactive solana status <signature> -n solana-mainnet
```

For sponsored fees, pass a Solana fee policy:

```bash
alchemy --json --no-interactive solana send <recipient_pubkey> 0.01 \
-n solana-mainnet \
--fee-sponsored \
--fee-policy-id <fee-policy-id>
```

Add `--token <mint>` for SPL tokens.
</Tab>
</Tabs>

Run `alchemy --json --no-interactive wallet disconnect` when the session is no longer needed.

## Machine-readable contract

Use the live CLI output as the source of truth for agents and skills:

```bash
npx -y @alchemy/cli@latest --json --no-interactive agent-prompt --scope wallet
```

Use the installed CLI when the agent needs to inspect the current machine's configured wallet:

```bash
alchemy --json --no-interactive agent-prompt --scope wallet
alchemy --json --no-interactive wallet status --verify
```

<Accordion title="Compact capability manifest">
Include this in an agent skill or system prompt when the agent cannot call
`agent-prompt` at runtime.

```json
{
"alchemyAgentWallets": {
"sourceOfTruth": {
"latestCli": "npx -y @alchemy/cli@latest --json --no-interactive agent-prompt --scope wallet",
"installedCli": "alchemy --json --no-interactive agent-prompt --scope wallet",
"sessionStatus": "alchemy --json --no-interactive wallet status --verify"
},
"session": {
"approval": "dashboard",
"privateKeyExposure": "never_exposed_to_agent",
"revocation": ["alchemy wallet disconnect", "dashboard"],
"expiryField": "expiresAt",
"capabilities": [
"evm.signMessage",
"evm.signTypedData",
"evm.signAuthorization",
"evm.prepareCalls",
"evm.sendCalls",
"solana.signTransaction"
]
},
"evm": {
"operations": [
"native_send",
"erc20_send",
"contract_call",
"erc20_approve_reset_revoke",
"swap_quote",
"swap_execute",
"bridge_quote",
"bridge_execute",
"status"
],
"sponsorshipFlags": ["--gas-sponsored", "--gas-policy-id <id>"],
"directRawTransactionSigning": false,
"limits": ["swaps_evm_mainnet_only", "bridges_evm_mainnet_only"]
},
"solana": {
"operations": ["sol_send", "spl_token_send", "status"],
"sponsorshipFlags": ["--fee-sponsored", "--fee-policy-id <id>"]
},
"agentRules": [
"Use --json --no-interactive in automation.",
"Run wallet status --verify before state-changing wallet actions.",
"Run balance, allowance, or quote checks before spending.",
"Use --dry-run where available before broadcast.",
"Treat sponsorship policies as fee controls, not wallet spend limits.",
"Disconnect or revoke the session after the workflow."
]
}
}
```
</Accordion>

## Operational details

<AccordionGroup>
<Accordion title="Dashboard controls">
Use the [Agent Wallets dashboard](https://dashboard.alchemy.com/products/agent-wallet/evm-wallet)
to create wallets, approve terminal sessions, fund wallets through onramps,
send from the wallet, and revoke sessions.
</Accordion>
<Accordion title="How sessions execute">
EVM session actions execute through Alchemy smart-wallet calls such as
`wallet_prepareCalls` and `wallet_sendCalls`. The CLI uses those calls for
nonce handling, preflight behavior, call IDs, status polling, batch-call
support where the command uses it, and optional paymaster capabilities.

Solana session actions sign transactions for supported CLI flows such as SOL
and SPL token sends.
</Accordion>
<Accordion title="Local wallet fallback">
Use a local wallet only when you intentionally want local key material:

```bash
alchemy wallet connect --mode local
alchemy wallet connect --mode local --import ./evm-private-key.txt
alchemy wallet use local
```

If both a session signer and a local EVM signer are configured, the CLI
defaults to the session signer and prints a warning.
</Accordion>
</AccordionGroup>

## Next steps

* [Alchemy CLI](docs/alchemy-cli)
* [Alchemy CLI wallets and signing](docs/alchemy-cli#wallets-and-signing)
* [Alchemy Agent Skills](docs/alchemy-agent-skills)
* [Alchemy Dashboard Agent Wallets](https://dashboard.alchemy.com/products/agent-wallet/evm-wallet)
14 changes: 7 additions & 7 deletions content/tutorials/build-with-ai/alchemy-cli.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -188,15 +188,15 @@ Most wallet-signed EVM commands accept `--signer session|local` to override the

### Wallets and signing

Use `alchemy wallet` to connect the signer used by onchain actions. EVM commands can use an [Agent Wallet session](docs/agent-wallets) approved through the Alchemy Dashboard or a local private key. The `session` signer refers to an Agent Wallet session, not an arbitrary browser wallet connection. Solana transaction commands currently use a local Solana wallet.
Use `alchemy wallet` to connect the signer used by onchain actions. EVM commands can use an [Agent Wallet session](docs/agent-wallets) approved through the Alchemy Dashboard or a local private key. Solana send commands can use an Agent Wallet session or a local Solana wallet. The `session` signer refers to an Agent Wallet session, not an arbitrary browser wallet connection.

Create, view, and revoke Agent Wallet sessions in the [Agent Wallets dashboard](https://dashboard.alchemy.com/products/agent-wallet/evm-wallet).

| Command | Description |
|---|---|
| `alchemy wallet connect` | Connect a wallet. Use `--mode session` for an Agent Wallet session or `--mode local` for a local wallet. Local mode supports `--chain evm\|solana\|both` and defaults to both. |
| `alchemy wallet connect --mode local --chain evm --import <path>` | Import a local EVM private key file |
| `alchemy wallet connect --mode local --chain solana` | Create or configure a local Solana wallet |
| `alchemy wallet connect` | Connect a wallet. Use `--mode session` for an Agent Wallet session or `--mode local` for local wallets. Session mode requests EVM and Solana capabilities. Local mode creates both EVM and Solana wallets. |
| `alchemy wallet connect --mode session --instance-name <name>` | Name the CLI instance shown during Dashboard approval |
| `alchemy wallet connect --mode local --import <path>` | Import a local EVM private key file |
| `alchemy wallet status` | Show Agent Wallet session, local EVM, local Solana, and active signer status. Add `--verify` to check the backend session. |
| `alchemy wallet address` | Display configured wallet addresses |
| `alchemy wallet qr` | Display an EVM or Solana wallet address as a QR code |
Expand All @@ -205,17 +205,17 @@ Create, view, and revoke Agent Wallet sessions in the [Agent Wallets dashboard](

### Solana

Solana transaction commands use a local Solana wallet. Use `--fee-sponsored` and `--fee-policy-id <id>` on supported Solana actions to request fee sponsorship.
Solana send commands can use an Agent Wallet session or a local Solana wallet. Use `--fee-sponsored` and `--fee-policy-id <id>` on supported Solana actions to request fee sponsorship.

```bash
alchemy wallet connect --mode local --chain solana
alchemy wallet connect --mode session
alchemy solana send <recipient> 0.1 -n solana-mainnet
alchemy solana status <signature>
```

| Command | Description |
|---|---|
| `alchemy solana send <to> <amount>` | Send native SOL. SPL token transfers are not yet supported. |
| `alchemy solana send <to> <amount>` | Send native SOL. Add `--token <mint>` for SPL token transfers. |
| `alchemy solana delegate approve --token-account <addr> --mint <addr> --delegate <addr> --amount <n> --decimals <n>` | Approve an SPL token delegate |
| `alchemy solana delegate revoke --token-account <addr>` | Revoke an SPL token delegate |
| `alchemy solana status [id]` | Check a Solana transaction signature; reads from stdin when omitted |
Expand Down
Loading