Getting Started with BotPay: Developer Guide to Gasless Stablecoin Streams

Introduction to BotPay Architecture

BotPay is designed to make programmable stablecoin payments as easy as calling an API. The protocol utilizes a smart-contract architecture deployed on the Arc Network L2, allowing developers to create second-by-second payment streams of USDC and EURC.

To minimize friction, BotPay incorporates Circle MPC Developer-Controlled Wallets and gas abstraction, removing the need for agents to hold native gas tokens.

In this guide, we will walk you through registering an agent, setting up a unified balance, and initializing your first payment stream.

---

Step 1: Registering Your Agent (ERC-8004)

Every agent on the BotPay network must register a cryptographic identity profile. This registry binds your agent's public address to its configuration metadata, endpoints, and owner permissions.

In the Bots Panel, click Register New Bot. Under the hood, this executes a transaction on the BotPay Registry contract:

// ABI signature for registering a bot
function registerBot(
  string calldata name,
  address walletAddress,
  string calldata description,
  string calldata endpointUrl
) external;

Once registered, your bot is assigned a unique on-chain ID and generates a secure API client secret (bp_sec_...). This secret is used to sign off-chain micropayment intents.

---

Step 2: Depositing Assets Into Unified Balance

BotPay's Unified Balance allows you to pool stablecoin liquidity in a single balance, abstracting away individual blockchain networks. Using Circle Gateway's deposit flow, you can deposit USDC from Ethereum, Base, Polygon, or Solana.

Your funds are automatically unified on-chain, ready to fuel outbound payment streams or off-chain nanopayment ledgers.

To verify your active balance programmatically:

const response = await fetch('/api/agent-wallet/balance');
const data = await response.json();
console.log('Unified USDC Balance:', data.balanceUsdc);

---

Step 3: Initializing an Escrow Payment Stream

BotPay streams operate by locking customer deposits into a secure escrow contract. The locked funds are then released to the provider bot second-by-second.

To initialize a stream, submit a payment intent request to the BotPay API:

const intent = await fetch('/api/bots/provision-wallet', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    botId: "agent-text-inference-v1",
    payerAddress: "0xCustomer...",
    flowRate: "0.0005", // USDC per second
    durationSeconds: 3600 // 1 hour duration
  })
});

Upon confirmation, the customer's wallet signs the deposit approval. The stream begins immediately on the Arc Network, running without manual user authorization.

---

Step 4: Tracking Streams and Requesting Netting Claims

As the agent performs tasks, its accrued earnings accumulate in the escrow state. Rather than executing frequent, expensive on-chain gas transactions to settle these earnings, the agent aggregates streams off-chain.

Once a day or once a batch, the developer triggers the Netting Settlement Engine:

const settleResult = await fetch('/api/netting/settle', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    batchId: "net_batch_8842",
    recipientAddress: "0xProviderAgent..."
  })
});

The engine aggregates all incoming and outgoing streams across the provider's active bots, nets the balances, and executes a single consolidated transaction to transfer the net USDC earnings to the provider's wallet.

---

Try It Live Today

You don't need real mainnet funds to start building. BotPay provides a friction-free testnet sandbox equipped with automated token faucets.

1. Head over to our Frictionless Sandbox to claim 10.00 testnet USDC. 2. Register your first agent mockup in the Bots Registry. 3. Test streaming API calls using the API Playground.