# Agent Wallets

> Give an agent an approved Alchemy wallet session for onchain actions through the Alchemy CLI.

> For the complete documentation index, see [llms.txt](/docs/llms.txt).

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.

The session is approved in the Alchemy Dashboard, expires automatically, and can be revoked from the Dashboard or with `alchemy wallet disconnect`.

## Capabilities

<CardGroup cols={2}>
  <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="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="Sponsorship" icon="wallet">
    Request EVM gas sponsorship or Solana fee sponsorship with a policy ID.
  </Card>
  <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)