From ecda59cab1ccba59a030a06c751cfc702f879db7 Mon Sep 17 00:00:00 2001 From: GigaHierz Date: Thu, 15 Oct 2026 23:28:17 +0100 Subject: [PATCH] docs(agents): add a page for giving an agent a wallet and test funds (#2263) Co-Authored-By: Claude Sonnet 5.5 --- build/agents/agent-wallet.mdx | 85 +++++++++++++++++++++++++++++++++++ build/agents/overview.mdx | 2 +- build/agents/x402.mdx | 2 +- docs.json | 1 + 4 files changed, 88 insertions(+), 2 deletions(-) create mode 100644 build/agents/agent-wallet.mdx diff --git a/build/agents/agent-wallet.mdx b/build/agents/agent-wallet.mdx new file mode 100644 index 000000000..492cfc0be --- /dev/null +++ b/build/agents/agent-wallet.mdx @@ -0,0 +1,85 @@ +--- +title: "Give Your Agent a Wallet and Test Funds" +sidebarTitle: "Agent Wallet" +description: Create an account for an agent, fund it on Celo Sepolia and send a first transfer before you wire it into x402 or MPP +--- + +This page is for agent developers who need an account their agent can sign with and some test funds. It ends with a transfer on Celo Sepolia, the testnet, so you know the account works before you add payments. Every example in the agents section that reads `AGENT_PRIVATE_KEY` assumes you have done this. + +## Prerequisites + +- Node.js 18 or later +- `npm install viem` + +## Generate an account + +An agent signs with a private key. Create one with [viem](/build/tools/libraries-sdks/viem): + +```ts +// generate-key.mjs +import { generatePrivateKey, privateKeyToAccount } from "viem/accounts"; + +const privateKey = generatePrivateKey(); +console.log("AGENT_PRIVATE_KEY=" + privateKey); +console.log("Address:", privateKeyToAccount(privateKey).address); +``` + +Run it once with `node generate-key.mjs`. Put the `AGENT_PRIVATE_KEY` line in a `.env` file that is in `.gitignore`, and keep the address for the next step. + + + Use a separate key for testing. Anyone who has the key controls everything the account holds. Never commit it, and never reuse a testnet key on mainnet. + + +## Get test funds + +The account needs CELO on Celo Sepolia (chain ID `11142220`) to pay gas. + +1. Open the [Celo Sepolia faucet](https://faucet.celo.org/celo-sepolia) and request CELO for the address from the previous step. It sends 1 CELO per request without signing in. +2. If you plan to test x402 or MPP, also get test USDC from the [Circle faucet](https://faucet.circle.com). The Celo Sepolia USDC token has 6 decimals, so 1 USDC is `1000000` base units. + +Other faucets and the network details are on the [network information](/learn/network/overview) page. + +## Send a first transfer + +This script reads the balance and sends a small amount of CELO to another address. Replace the recipient with an address you control. + +```ts +// first-transfer.mjs +// Celo Sepolia (11142220), native CELO, 18 decimals +import { createPublicClient, createWalletClient, http, parseEther, formatEther } from "viem"; +import { privateKeyToAccount } from "viem/accounts"; +import { celoSepolia } from "viem/chains"; + +const account = privateKeyToAccount(process.env.AGENT_PRIVATE_KEY); +const publicClient = createPublicClient({ chain: celoSepolia, transport: http() }); +const walletClient = createWalletClient({ account, chain: celoSepolia, transport: http() }); + +const balance = await publicClient.getBalance({ address: account.address }); +console.log("Balance:", formatEther(balance), "CELO"); + +const hash = await walletClient.sendTransaction({ + to: "0xYourOtherAddress", // example, replace with an address you control + value: parseEther("0.01"), +}); +const receipt = await publicClient.waitForTransactionReceipt({ hash }); +console.log("Status:", receipt.status, "Hash:", hash); +``` + +Run it with your key in the environment, for example `node --env-file=.env first-transfer.mjs`. + +You are done when it prints `Status: success`. Look the hash up on the [Celo Sepolia explorer](https://celo-sepolia.blockscout.com) to see the transaction. + +## Troubleshooting + +| Symptom | Cause | Fix | +|---------|-------|-----| +| `insufficient funds for gas` | The account has no CELO on Celo Sepolia | Request CELO from the faucet, then check the balance | +| `Balance: 0 CELO` after the faucet | The faucet sent funds to a different address, or to mainnet | Check the address and that you are on Celo Sepolia, not Celo mainnet | +| USDC transfer amount is off by a factor of 10^12 | USDC has 6 decimals and CELO has 18 | Use `parseUnits("1", 6)` for USDC and `parseEther` for CELO | + +## Next steps + +- [x402](/build/agents/x402) - charge or pay per request with this account +- [MPP](/build/agents/mpp) - the same flow through the Celo facilitator +- [Fee abstraction for agents](/build/agents/overview#fee-abstraction-for-agents) - pay gas in a stablecoin so the account needs no CELO +- [Celina](/build/agents/mcp/celina) - give an LLM a wallet through a tool instead of a key you manage diff --git a/build/agents/overview.mdx b/build/agents/overview.mdx index 6b7c7dc14..67c3b52f7 100644 --- a/build/agents/overview.mdx +++ b/build/agents/overview.mdx @@ -63,7 +63,7 @@ Both settle on-chain in seconds, making them well-suited to paid APIs, pay-per-u ## Giving an agent a wallet -An agent that pays for things needs an account it can read from and sign with. You can wire this up directly with [viem](/build/tools/libraries-sdks/viem), or use a tool that exposes the calls to an LLM: [Celina](/build/agents/mcp/celina) covers balances, transfers, DeFi, governance, staking and Self Agent ID through an SDK, an MCP server, a REST API, and a read-only Telegram bot. The SDK and MCP server are open source. +An agent that pays for things needs an account it can read from and sign with. To create one and fund it on Celo Sepolia, follow [Give your agent a wallet and test funds](/build/agents/agent-wallet). You can wire this up directly with [viem](/build/tools/libraries-sdks/viem), or use a tool that exposes the calls to an LLM: [Celina](/build/agents/mcp/celina) covers balances, transfers, DeFi, governance, staking and Self Agent ID through an SDK, an MCP server, a REST API, and a read-only Telegram bot. The SDK and MCP server are open source. ## Paying by card and signing in to websites diff --git a/build/agents/x402.mdx b/build/agents/x402.mdx index fc810c6c5..d6a2c515c 100644 --- a/build/agents/x402.mdx +++ b/build/agents/x402.mdx @@ -248,7 +248,7 @@ A facilitator you do not know deserves the same checks as any other service that - Confirm who operates it. - Before your server accepts a payment, check the asset, amount and `payTo` address against what you priced. Do not rely on the facilitator's response alone. - Confirm the settlement transaction on-chain before you deliver anything valuable. A facilitator cannot redirect funds, because the payer signs `to` and `value`, but a settlement claim should still be checked. -- Test against Celo Sepolia (`https://api.x402.sepolia.celo.org` for the Celo facilitator) before sending mainnet funds. +- Test against Celo Sepolia (`https://api.x402.sepolia.celo.org` for the Celo facilitator) before sending mainnet funds. To create a test account and fund it, see [Give your agent a wallet and test funds](/build/agents/agent-wallet). thirdweb runs a hosted x402 facilitator that supports Celo — see the [thirdweb x402 docs](https://portal.thirdweb.com/x402). diff --git a/docs.json b/docs.json index 126c98b90..e1aa61fef 100644 --- a/docs.json +++ b/docs.json @@ -184,6 +184,7 @@ "pages": [ "build/agents/overview", "build/agents/use-docs-with-ai", + "build/agents/agent-wallet", "build/agents/8004", "build/agents/self-agent-id", "build/agents/agent-vault",