> For the complete documentation index, see [llms.txt](https://docs.grandprotocol.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.grandprotocol.org/features/agent-wallets.md).

# Agent Wallets

Every agent in Grand Protocol has a non-custodial wallet on Robinhood Chain. The wallet is the source of funds for all payments the agent makes. Grand Protocol cannot move funds without a valid transaction signed by the agent's key.

***

## How wallets work

Agent wallets are **smart contract wallets** on Robinhood Chain, deployed by the Grand Protocol factory contract using `CREATE2` with the agent's unique ID as the salt. The address is deterministic — the same agent ID always produces the same wallet address.

USDC is held directly in the wallet contract as an ERC-20 balance. When an agent makes a payment, Grand Protocol constructs a Robinhood Chain transaction signed by the agent's key, transfers USDC to the payee, and records the payment in the on-chain ledger.

***

## Creating a wallet

```bash
curl -X POST https://api.grandprotocol.org/v1/wallets \
  -H "Authorization: Bearer $GRAND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "my-agent" }'
```

```json
{
  "agentId": "my-agent",
  "address": "0x7A3f9C2E8b41D6a05F1c94E2B8D3a7C6e5F0b1A2",
  "balance": { "usdc": 0 },
  "network": "robinhood-mainnet"
}
```

***

## Funding a wallet

### Via dashboard

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

### Via direct transfer

Send USDC (ERC-20) to the wallet address from any EVM-compatible wallet connected to Robinhood Chain (chain ID 4663). Funds arrive within one block confirmation (100ms block time).

Send USDC on Robinhood Chain only. Tokens sent on any other network cannot be recovered.

### Via API

```bash
curl -X POST https://api.grandprotocol.org/v1/wallets/my-agent/fund \
  -H "Authorization: Bearer $GRAND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "usdc": 100 }'
```

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

***

## Checking balance

```bash
curl https://api.grandprotocol.org/v1/wallets/my-agent \
  -H "Authorization: Bearer $GRAND_API_KEY"
```

```json
{
  "agentId": "my-agent",
  "address": "0x7A3f9C2E8b41D6a05F1c94E2B8D3a7C6e5F0b1A2",
  "balance": { "usdc": 42.50 },
  "network": "robinhood-mainnet"
}
```

***

## Withdrawing funds

Withdraw USDC from an agent wallet to any Robinhood Chain address:

```bash
curl -X POST https://api.grandprotocol.org/v1/wallets/my-agent/withdraw \
  -H "Authorization: Bearer $GRAND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "0x9bC4e21F7d3A85b6E0c2D4f8A1B3c5D7e9F0a2B4",
    "usdc": 20
  }'
```

Withdrawals require authentication and are logged on-chain.

***

## Signing key management

Each agent wallet is controlled by a secp256k1 signing key, the same key type used by every Ethereum-compatible wallet. Grand Protocol generates and stores the key in encrypted form in your account. The private key never leaves Grand Protocol's key management service.

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

```bash
curl -X POST https://api.grandprotocol.org/v1/wallets/import \
  -H "Authorization: Bearer $GRAND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "my-agent",
    "privateKey": "0x<64 hex characters>"
  }'
```

The key must be a 32-byte secp256k1 private key, hex-encoded with a `0x` prefix. Once imported, Grand Protocol stores the key 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
curl -X POST https://api.grandprotocol.org/v1/wallets \
  -H "Authorization: Bearer $GRAND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "my-agent-compute" }'

curl -X POST https://api.grandprotocol.org/v1/wallets \
  -H "Authorization: Bearer $GRAND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "my-agent-data" }'
```

Each agent ID corresponds to a distinct contract wallet and a distinct USDC balance.

***

## On-chain visibility

Because agent wallets are contracts on Robinhood Chain, every transaction is publicly visible on the Robinhood Chain explorer. Anyone with the wallet address can verify the full payment history independently of Grand Protocol.

```bash
curl https://api.grandprotocol.org/v1/wallets/my-agent \
  -H "Authorization: Bearer $GRAND_API_KEY"
# Returns address field: 0x7A3f9C2E8b41D6a05F1c94E2B8D3a7C6e5F0b1A2
# Open: https://robinhoodchain.blockscout.com/address/0x7A3f9C2E8b41D6a05F1c94E2B8D3a7C6e5F0b1A2
```

***

## Non-custodial guarantee

Grand Protocol holds the encrypted agent signing key, but cannot unilaterally move funds. Every payment transaction requires:

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

There is no administrative override. Grand Protocol support cannot transfer funds from an agent wallet without the agent key's signature.

***

## Further reading

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.grandprotocol.org/features/agent-wallets.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.