Guide

Vibe Coding with Bitcoin Agents

Build AI agents with their own Bitcoin wallets and payment-gated APIs. No coding experience required.

What you'll build
🤖

Claude Code Setup

An AI coding assistant that writes and runs code in your terminal.

Build in hours what used to take weeks.

💳

Agent Wallet

Your AI gets its own Stacks wallet to hold and send funds.

Let your agent earn and spend on your behalf.

⚡

x402 Endpoints

Payment-gated APIs that accept STX, sBTC, or USDCx.

Monetize your agent's work while you sleep.

The Guide

Follow the steps below. Click each section to expand. ~30 min total

1

Setting Up Claude Code

~5 min

Claude Code lets you build with AI that can read, write, and run code. Choose whichever setup works best for you.

Option A: Claude App (Easiest)

If you have the Claude desktop app, Claude Code is built right in. Just open a project folder and start building.

  1. Download Claude for Desktop if you don't have it
  2. Open a project folder (or create a new one)
  3. Start chatting — Claude can now read and edit files in that folder

Option B: Terminal

Prefer the command line? Install Claude Code globally via npm.

Step 1: Install Node.js

Go to https://nodejs.org and download the LTS version. Open the downloaded file and follow the installer prompts.

Step 2: Open a new Terminal window

Close Terminal and open it again. This ensures Node.js is ready to use.

Step 3: Install Claude Code

npm install -g @anthropic-ai/claude-code

Step 4: Run it

claude

The first time you run it, Claude Code will ask you to log in with your Anthropic account. Follow the prompts.

💡
Once you're set up, try asking: "What can you help me build?"

Your AI agent needs its own wallet to send and receive payments. We'll use the stx402 MCP to give Claude wallet capabilities.

Step 1: Add the Wallet Capability to Claude

Copy and paste this command into Claude Code:

claude mcp add stx402 npx stx402-agent -e NETWORK=mainnet

Claude will confirm the MCP server has been added.

Step 2: Create Your Agent's Wallet

Type this to Claude:

"Create a secure Stacks wallet"

Claude will ask you to set a password. Choose a strong password and remember it — this encrypts your wallet locally.

That's it. Your agent now has a wallet.

Step 3: Fund the Wallet

Ask Claude:

"What is my wallet address?"

Send STX or sBTC to this address to fund your agent's wallet.

🧪
Want to practice first? Use NETWORK=testnet in step 1, then get free test STX from the Stacks faucet.

What Your Agent Can Do Now

Once set up, your agent can:

  • Hold and transfer STX and sBTC
  • Interact with Stacks smart contracts
  • Pay for x402 API services automatically
  • Trade on ALEX DEX
  • Use Zest Protocol for lending/borrowing

Ask Claude "What can you do with my wallet?" to explore capabilities.

🔒
Security tips: Your wallet is encrypted and stored locally (~/.stx402/). Never share your password or mnemonic phrase.

x402 lets you charge for API access using crypto. When someone hits your endpoint without paying, they get a 402 "Payment Required" response. Once they pay, they get the content.

The AIBTC x402 Stack

  • x402.aibtc.dev (testnet) — The API host
  • x402-sponsor-relay — Gasless transactions for agents
  • Supported tokens: STX, sBTC, USDCx

Option A: Use Existing x402 API

The easiest path — consume AIBTC's existing endpoints:

# This returns 402 with payment requirements
curl https://x402.aibtc.dev/inference/chat

Ask Claude: "Help me write a script that calls x402.aibtc.dev and handles the payment flow."

Option B: Deploy Your Own Endpoint

Create your own payment-gated API:

# Clone the x402-api template
git clone https://github.com/aibtcdev/x402-api.git
cd x402-api
npm install

Ask Claude: "Help me add an endpoint that charges 0.001 STX to return a joke."

# Deploy to Cloudflare
npx wrangler login
npx wrangler deploy --env staging

Option C: Gasless Transactions

Use the sponsor relay so your agent doesn't need STX for gas:

POST https://x402-relay.aibtc.dev/relay

Now you have all the pieces. Here's the complete flow:

  1. Your agent has a wallet with testnet STX
  2. Someone calls your x402 endpoint and gets a 402 response
  3. They pay in STX, sBTC, or USDCx
  4. Your endpoint verifies and returns the content
  5. Payment goes to your agent's wallet

Example: AI Advice Agent

Ask Claude:

🚀
"Help me create an x402 endpoint that charges 0.01 STX for AI-generated advice. Deploy it on Cloudflare Workers."

Claude will help you set up routes, connect to an LLM, handle payments, and deploy.

Quick Reference

Everything you need in one place.

Endpoints

x402 API (Testnet) x402 API (Mainnet) Sponsor Relay Stacks Faucet

Repositories

Stacks MCP Server x402 API Template Sponsor Relay All AIBTC Repos

Payment Tokens

STX Native Stacks token
sBTC Bitcoin on Stacks
USDCx USDC bridged to Stacks

Get Help

AIBTC Discord Stacks Documentation AIBTC Docs

Common Questions

Do I need to know how to code?
Not really. Claude Code writes the code for you. Just describe what you want in plain English.
Is this safe to use with real money?
Start on testnet. Only move to mainnet once you understand what's happening. Always use a dedicated agent wallet, never your personal funds.
What can I build with this?
  • Pay-per-query AI endpoints
  • Premium content APIs
  • Agent-to-agent payment flows
  • Automated trading bots
  • DAO participation tools
What if something breaks?
Ask Claude. Paste the error message and ask it to help you debug. That's the vibe coder way.

Join the Community

Share what you build, get help, and connect with other builders.

Join AIBTC Discord