# Send a payment with an AI agent

> For the complete documentation index, see [llms.txt](https://bsvblockchain.com/docs/llms.txt).

Have an AI agent build and run a first testnet payment from the BSV blockchain docs, while you give it your address and approve the payment in BSV Desktop.

import AgentPaymentRoles from '/snippets/AgentPaymentRoles.jsx';

Ask an AI agent for your first BitcoinSV (BSV) payment and let it read these docs, write the scripts and run them, while you keep the steps that move coins. The agent connects to your testnet wallet in [BSV Desktop](https://desktop.bsvb.tech/), and no private key goes in the code. Use it when you build with [Claude Code](https://code.claude.com/docs/en/overview) and want to see how it handles a payment before you trust it with a real project. The example runs standalone in an empty folder, and at the end you have a testnet payment you approved and its transaction ID on the explorer.

## Before you begin

- [Claude Code](https://code.claude.com/docs/en/overview) installed.
- Node.js 22 or newer.
- BSV Desktop on testnet with free testnet coins. If you do not have it yet, follow [Set up a testnet wallet](https://bsvblockchain.com/docs/get-started/quick-start-browser/#set-up-a-testnet-wallet) and [Get free testnet coins](https://bsvblockchain.com/docs/get-started/quick-start-browser/#get-free-testnet-coins) in the web app guide.

## How it works

The agent does the work that happens in code, and you do the work that happens in the wallet:

<AgentPaymentRoles />

- Agent, works in the code: reads these docs, installs `@bsv/sdk`, writes a script that connects to BSV Desktop through `WalletClient`, checks that the wallet is on testnet, runs the payment and reads its status from BSV Broadcaster.
- You, work in the wallet: get testnet coins if the wallet is empty, give the agent your testnet address and approve the payment in BSV Desktop with **Authorize**.

The agent reads the docs through the BSV blockchain docs server, follows the rules in your project, and stops to ask you for each step on your side.

## Set up the project

Create an empty folder for the agent and open it in the terminal, then complete these steps in it:

**1. Connect the BSV blockchain docs server**

Add the docs server, as in [Connect your AI tool with MCP](https://bsvblockchain.com/docs/build-with-ai/mcp/):

```bash
claude mcp add --transport http bsv-docs https://bsvblockchain.com/docs/mcp
```

```text
Added HTTP MCP server bsv-docs with URL: https://bsvblockchain.com/docs/mcp to local config
```

**2. Add the bsv-dev rules**

Create `CLAUDE.md` in the folder and paste the `bsv-dev` rules from [Give agents the docs in Markdown](https://bsvblockchain.com/docs/build-with-ai/llm-resources/). With the `bsv-dev` skill installed, the agent offers you the same rules, and you add them to the file yourself ([Install the BSV blockchain agent skill](https://bsvblockchain.com/docs/build-with-ai/skill/)). Claude Code reads this file at the start of every session. The rules tell the agent to read the BSV blockchain docs, build on testnet, keep private keys out of the code and ask you for the coins and the approval.

## Ask the agent for the payment

With the project ready, make the request and check what the agent builds:

**1. Send the request**

Run `claude` in the project folder and type the request:

```text
Send my first BSV payment from a small Node.js script. Build it and run it.
```

The agent reads the docs, installs `@bsv/sdk` and writes its scripts, for example `pay.mjs`. Claude Code asks you before the agent runs a command such as `npm install` or `node`, so read each command before you allow it. Before it pays, the agent checks the connection to BSV Desktop and confirms that the wallet is on testnet. Then it stops and asks you for the steps it cannot do: testnet coins if the wallet is empty, your testnet address, and the approval in BSV Desktop.

**2. Check the script**

While the agent waits, open the payment script it wrote and check that it:

- connects to the wallet with `new WalletClient(...)` from `@bsv/sdk`, with no private key, recovery phrase or `.env` secret;
- stops unless the `network` field returned by `wallet.getNetwork()` is `testnet`;
- sends the payment with `wallet.createAction(...)`, to the address and amount you expect;
- after the wallet returns the transaction ID, sends the transaction to BSV Broadcaster and reads its status there;
- reports the payment as final only at `SEEN_ON_NETWORK`, `MINED` or `IMMUTABLE`, and stops with an error on `REJECTED` or `DOUBLE_SPEND_ATTEMPTED`.

The script is the agent's own, so names and messages vary from run to run.

## Give the agent your address

The agent pays to your own testnet address, so copy it in BSV Desktop and send it to the agent:

**1. Open the Receive screen**

In BSV Desktop, open **Payments**, then **Receive**.

**2. Copy your testnet address**

Select the **BSV ADDRESS** tab and click **Copy address**. A testnet address starts with `m` or `n`.

The **WALLET PAYMENT** tab opens first and copies a `peerpay:` link, not an address.

<img src="https://bsvblockchain.com/docs/images/pay-with-ai-agent/01-receive-bsv-address.png" alt="The Receive screen of BSV Desktop with the BSV ADDRESS tab selected and the Copy address button below a blurred QR code" />

**3. Reply to the agent**

Tell the agent that the wallet has coins and give it the address, in place of `YOUR_TESTNET_ADDRESS`:

```text
My wallet already has testnet coins. My address is YOUR_TESTNET_ADDRESS
```

## Approve the payment

A sent payment cannot be undone, so check the request in BSV Desktop before you approve it:

**1. Check the Spending Request**

The agent runs the payment script, which waits until you answer in BSV Desktop. The wallet opens a **Spending Request** with the app name the script set, the payment description and the total with the fee, for example 1,094 satoshis for a 1,000 satoshi payment. The fee depends on the coins the wallet spends, so the total can differ. A satoshi is the smallest unit of BSV, and 100,000,000 satoshis make 1 BSV. Check that the app name is the one the script set and that the amount is the one you expect.

**2. Authorize the payment**

Click **Authorize**:

<img src="https://bsvblockchain.com/docs/images/pay-with-ai-agent/02-spending-request.png" alt="The Spending Request window of BSV Desktop from first-payment.local for a payment named My first BSV payment, with the total of 1,094 satoshis and the Deny and Authorize buttons" />

After you approve, the script prints the transaction ID, sends the transaction to [BSV Broadcaster](https://bsvblockchain.com/docs/guides/services/broadcasting/) and prints its status, for example:

```text
Wallet network: testnet
Requesting a payment of 1000 sats to YOUR_TESTNET_ADDRESS. Approve it in BSV Desktop...
Transaction ID: <64 character transaction ID>
Arcade broadcast: success broadcast successful
Arcade status: ACCEPTED_BY_NETWORK
Arcade status: SEEN_ON_NETWORK
Payment is final.
Explorer (for viewing only): https://test.whatsonchain.com/tx/<64 character transaction ID>
```

The labels in this output say Arcade, the former name of BSV Broadcaster. For an app, a payment of this size is final when BSV Broadcaster reports `SEEN_ON_NETWORK` or later and no competing transaction exists, with no wait for a block. At that status the transaction is not in a block yet. The explorer link is only to see the transaction: if [WhatsOnChain](https://test.whatsonchain.com/) shows **This page cannot be found**, it has not listed the payment yet, so wait a minute and reload.

Your **Available balance** in BSV Desktop goes down by the amount plus the fee. While the **BSV ADDRESS** tab is open, BSV Desktop adds the payment back to your wallet, so only the fee is spent.

## Next steps

With the payment sent, check it on the explorer, then start a real project:

- [Verify your payment on the explorer](https://bsvblockchain.com/docs/get-started/verify/)
- [Start a project from a template](https://bsvblockchain.com/docs/get-started/project-starter/)