# Agent Wallets

Every agent in Grace Protocol has a non-custodial Solana wallet. The wallet is the source of funds for all payments the agent makes. Grace Protocol cannot move funds without a valid signed instruction from the agent's keypair.

***

## How wallets work

Agent wallets are **program-derived addresses (PDAs)** on Solana, derived from the agent's unique ID and the Grace Protocol on-chain program. The PDA is deterministic — the same agent ID always produces the same wallet address.

USDC is held in a Solana Associated Token Account (ATA) owned by the PDA. When an agent makes a payment, Grace Protocol constructs a Solana transaction signed by the agent's keypair, transfers USDC to the payee, and records the payment in the on-chain ledger.

***

## Creating a wallet

```bash
grace wallet create --agent my-agent
```

```
Agent wallet created.

  Agent:    my-agent
  Address:  7xKXtg2xpAGMq8KLwpSodE9LFKq8Z1EscezSShpump
  Balance:  0.00 USDC
  Network:  Solana Mainnet
```

***

## Funding a wallet

### Via dashboard

Deposit USDC to the wallet address at [app.graceprotocol.org](https://app.graceprotocol.org). The dashboard also supports card top-ups that convert to USDC on-chain automatically.

### Via direct transfer

Send USDC (SPL Token) to the wallet address from any Solana wallet. Funds arrive within one block confirmation (under 1000ms).

### Via CLI

```bash
grace wallet fund my-agent --usdc 100
```

This initiates a transfer from the funding source configured in your account settings.

***

## Checking balance

```bash
grace wallet balance --agent my-agent
```

```
Agent:    my-agent
Address:  7xKXtg2xpAGMq8KLwpSodE9LFKq8Z1EscezSShpump
Balance:  42.50 USDC
Network:  Solana Mainnet
```

***

## Withdrawing funds

Withdraw USDC from an agent wallet to any Solana wallet address:

```bash
grace wallet withdraw my-agent \
  --to 9zXKtg2xpAGMq8KLwpSodE9LFKq8Z1EscezSShpump \
  --usdc 20
```

Withdrawals require authentication and are logged on-chain.

***

## Keypair management

Each agent wallet is controlled by an Ed25519 keypair. Grace Protocol generates and stores the keypair in encrypted form in your account. The private key never leaves Grace Protocol's key management service.

For Enterprise accounts with bring-your-own-key (BYOK) requirements:

```bash
grace wallet import my-agent --keypair ./my-agent-keypair.json
```

The keypair file must be in Solana CLI JSON format (a 64-byte array). Once imported, Grace Protocol stores the keypair under your account's KMS encryption.

***

## Multiple wallets

Each agent has exactly one wallet. If you need multiple spending accounts within a single agent (for example, separating payments by task type), create separate agent IDs:

```bash
grace wallet create --agent my-agent-compute
grace wallet create --agent my-agent-data
```

Each agent ID corresponds to a distinct PDA and a distinct USDC balance.

***

## On-chain visibility

Because agent wallets are Solana PDAs, every transaction is publicly visible on Solana Explorer. Anyone with the wallet address can verify the full payment history independently of Grace Protocol.

```bash
grace wallet explorer my-agent
# Opens: https://explorer.solana.com/address/7xKXtg2xpAGMq8KLwpSodE9LFKq8Z1EscezSShpump
```

***

## Non-custodial guarantee

Grace Protocol holds the encrypted agent keypair, but cannot unilaterally move funds. Every payment transaction requires:

1. A valid signed instruction from the agent's keypair
2. A spend policy check that passes
3. A valid x402 or MPP payment request from an authorized domain

There is no administrative override. Grace Protocol support cannot transfer funds from an agent wallet without the keypair signature.

***

## Further reading

* [Spend policies](/features/spend-policies.md)
* [Security and key management](/platform/security.md)
* [REST API reference](/platform/architecture.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.graceprotocol.org/features/agent-wallets.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.