Agent Wallet with Circle

Give an agent a Circle wallet and ask it to find a service for a task, such as checking the weather. It searches the Circle Agent Marketplace, estimates the price, and requests approval for recognized payment commands before buying a response with USDC. It uses the service's result to answer your question. Payments use x402, a protocol for paying for individual requests.

Why we built this

Agents stop at paywalls, missing API keys, and account signups, and the usual answer is to set up access for every service you might need. This template gives the agent a wallet and a marketplace, so it can find and purchase a service while you review the request. Circle supplies the wallet and service-payment tools; Mastra supplies the conversation and approval interface.

Prerequisites

• OpenAI API key - OPENAI_API_KEY powers the default model, openai/gpt-5.6-sol. The optional AGENT_MODEL override supports other models with the corresponding provider credentials.
• Circle Agent Stack - wallet sign-in uses an email address and an emailed code. Circle needs no API key here; paid requests need a wallet funded with USDC on a chain supported by the chosen service.

Quickstart 🚀

1. Clone the template
   • Run npx create-mastra@latest --template https://github.com/mastra-ai/template-circle.
   • Change into the project directory created by the command and run npm install if setup did not install dependencies.
2. Add your API keys
   • Run cp .env.example .env and fill in the values described under Prerequisites.
3. Start the dev server
   • Run npm run dev.
   • Open Mastra Studio, select Circle Payment Agent, and ask: “What services are available for weather data? Do not buy anything yet.”
   • On a fresh workspace, the agent fetches Circle's setup instructions and installs its command-line interface (CLI) and skills. Follow the sign-in conversation, review the terms approval, and provide your email and code when asked. The expected result is a list of available weather services and their pricing, without purchasing a response.

Try it out

• Ask “Check my wallet balance.” Look for the available balance before choosing a paid service.
• Ask “Find a weather service for London and estimate the cost of one request.” Compare the proposed service, payment chain, and price. Listings and prices depend on the live marketplace.
• Ask “Use that service to get London's weather.” With a funded wallet, the agent can request payment approval and use the purchased response to answer.
• Decline a payment approval, then ask “Find another option.” The declined tool call should not execute, and the agent can search for another service.

Customization

• Open the project in your coding agent and describe the outcome you want. For example: “Make this a travel assistant that finds weather and flight-status services and shows the price before asking to buy a response. Explore the code and propose a plan before making changes.”
• Connect your own front end with the Mastra Client SDK. Adapt the caller identity and sign-in flow in studio.ts and control-plane.ts to your authenticated users.

Before you leave it running

The agent signs in to Circle on mainnet and can spend real USDC. Review the network, amount, and recipient before approving a payment.

approval.ts matches known spending commands and requests approval in Studio. These command checks are not a security boundary. Other commands can run without approval, and the local shell can delete files, install packages, and fetch from the network. Use Circle's circle wallet limit set command in your own terminal to configure spending limits for the agent's wallet; the agent is blocked from changing those limits through its shell.

Caller workspaces are selected by user-id in requestContext. Studio uses the identity studio, with its own CLI session rather than the session in your ordinary home directory. Nothing here authenticates caller IDs or provides operating-system isolation between workspaces. Add authentication before exposing the server to other users.

Studio collects the emailed sign-in code in chat, so it passes through the model. The submit-code tool masks its displayed input, but the original message and arguments can still contain the code. For a custom front end, the /circle/* routes allow a trusted backend to handle sign-in outside the conversation. CONTROL_PLANE_TOKEN is the shared secret for those routes, sent in the x-control-plane-token header; they refuse requests when it is unset. It is not needed for the Studio walkthrough.

Wallet sessions and skills are stored on disk, but chat history and pending approvals use in-memory storage and are lost when the server restarts. On networks that require certificates from the system trust store, the optional NODE_OPTIONS=--use-system-ca setting is available in .env.example.

Documentation

• Circle CLI reference
• Circle Skills and setup instructions - wallet and marketplace guidance fetched at runtime.
• Agent implementation - model, workspace, and setup behavior.
• Sign-in tools - terms approval and email-code submission in Studio.

About Mastra templates

This template was contributed by Circle to show how Mastra works with Circle's Agent Stack to discover and pay for services. Circle's skills supply wallet and marketplace guidance; the template adds the agent's operating instructions, approval checks, and Studio sign-in tools.

Open issues and pull requests in mastra-ai/template-circle.