Skip to content

Code examples for AI agents

Runnable examples for buying crypto ads with an AI agent: curl, a JavaScript client, x402 payments on five networks, MCP, ElizaOS and Coinbase AgentKit.

Updated

Everything an agent needs to buy advertising from CryptoAd Network, as code you can run. The files are served from this site, so there is nothing to clone and no account to open anywhere. Every example below ran against the live API, and the ones that pay made real purchases.

Get the files

mkdir cryptoad-agent-examples && cd cryptoad-agent-examples
BASE=https://cryptoadvertising.net/agent-examples
for f in package.json client/cryptoad.mjs client/wallet.mjs \
  examples/01-formats-and-quote.mjs examples/02-buy-credit.mjs \
  examples/03-place-ad.mjs examples/04-check-ad.mjs examples/05-mcp.mjs \
  examples/06-pay-on-solana.mjs examples/07-pay-on-bnb-chain.mjs examples/curl.sh
do curl -fsS --create-dirs -o "$f" "$BASE/$f"; done
printf 'api-key.txt\nnode_modules\n' > .gitignore
npm install

The last-but-one line matters if the folder ever becomes a repository: the examples write the account's API key to api-key.txt.

They need Node 20 or newer. The dependencies are the x402 client libraries and viem, pinned to exact versions in package.json. The code is MIT licensed (LICENSE).

What each file does

Without paying anything

node examples/01-formats-and-quote.mjs
node examples/02-buy-credit.mjs 5 --price
bash examples/curl.sh

The second line prints what $5 of credit costs on each network and token: the 402 Payment Required answer, which creates nothing.

Buy credit, then place an ad

WALLET_PRIVATE_KEY=0x... node examples/02-buy-credit.mjs 5
node examples/03-place-ad.mjs https://your-site.example/
node examples/04-check-ad.mjs

The first line pays 5 USDC on Base and writes the API key to api-key.txt. The key is shown once and cannot be recovered, because there is no email address behind it. Run it again and the credit is added to the same account: the key file is read, never replaced. The wallet needs USDC and no ETH: the payment is a signature, and the network fee is paid for you. Set X402_NETWORK=eip155:137 for Polygon or eip155:42161 for Arbitrum.

Use a wallet made for this purpose that holds only what the agent may spend.

The client, in your own code

import { CryptoAd } from "./client/cryptoad.mjs";
import { payingFetch } from "./client/wallet.mjs";

const api = new CryptoAd({
  fetch: payingFetch({ privateKey: process.env.WALLET_PRIVATE_KEY, maxUsd: 5 }),
});
const { api_key, balance } = await api.buyCredit(5);
const { ad } = await api.createAd({
  product: "PTC",
  name: "Launch week",
  landing_url: "https://your-site.example/",
  ad_title: "Try the new wallet",
  ad_description: "Open the page and look around.",
  product_options: { clicks: 100, duration_seconds: 10 },
});

payingFetch pays only CryptoAd Network's receiving address and never more than the cap you give it. It reads the 402 answer itself first and refuses anything else before a signature exists.

Pay with USDC on Solana

node examples/06-pay-on-solana.mjs 5 --price
SOLANA_SECRET_KEY=... node examples/06-pay-on-solana.mjs 5

SOLANA_SECRET_KEY is the secret key the way wallets export it (base58), or its 32-byte seed in hex. On Solana the payment is a transaction your wallet signs, with the fee paid by the account the 402 answer names. The wallet needs USDC and no SOL. The part that differs from the EVM networks is small:

import { createKeyPairSignerFromBytes, getBase58Encoder } from "@solana/kit";
import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactSvmScheme } from "@x402/svm";

const NETWORK = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
const signer = await createKeyPairSignerFromBytes(
  getBase58Encoder().encode(process.env.SOLANA_SECRET_KEY),
);
const pay = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: NETWORK, client: new ExactSvmScheme(signer) }],
  spendControls: { maxAmountPerPayment: 5 },
});
const response = await pay("https://cryptoadvertising.net/api/v1/credits/5", { method: "POST" });

Pay with USDT or USDC on BNB Chain

node examples/07-pay-on-bnb-chain.mjs 5 --price
WALLET_PRIVATE_KEY=0x... node examples/07-pay-on-bnb-chain.mjs 5
WALLET_PRIVATE_KEY=0x... TOKEN=USDC node examples/07-pay-on-bnb-chain.mjs 5

BNB Chain's tokens are paid through Permit2, and two things differ:

  1. Once per token, the wallet approves the Permit2 contract. That is an ordinary transaction and needs a little BNB. The example sends it when the approval is missing. Payments after it need no BNB.
  2. The x402 client pays only tokens it knows by default, and these are not among them. Name the token, with the most one payment may be:
import { ExactEvmScheme } from "@x402/evm";
import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { privateKeyToAccount } from "viem/accounts";

const USDT = "0x55d398326f99059fF775485246999027B3197955"; // 18 decimals
const account = privateKeyToAccount(process.env.WALLET_PRIVATE_KEY);
const pay = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: "eip155:56", client: new ExactEvmScheme(account) }],
  spendControls: {
    allowedAssets: [
      { network: "eip155:56", asset: USDT, maxAmountPerPayment: "5000000000000000000" },
    ],
  },
  // The 402 answer offers two tokens on this network: choose one.
  paymentRequirementsSelector: (_version, accepts) =>
    accepts.find((entry) => entry.asset.toLowerCase() === USDT.toLowerCase()) ?? accepts[0],
});
const response = await pay("https://cryptoadvertising.net/api/v1/credits/5", { method: "POST" });

Without the approval, the payment is answered 402 and nothing has moved.

With curl alone

API=https://cryptoadvertising.net/api/v1

# The formats, their fields and prices
curl -s "$API/formats"

# The exact price of an order. Creates nothing.
curl -s "$API/quote" -H 'content-type: application/json' -d '{
  "product": "PTC",
  "name": "Quoted with curl",
  "landing_url": "https://example.com/",
  "ad_title": "Have a look at this page",
  "ad_description": "Open the page and look around for ten seconds.",
  "product_options": { "clicks": 1000, "duration_seconds": 10 }
}'

# The price of $5 of ad credit: 402 with the x402 payment requirement
curl -s -i -X POST "$API/credits/5"

Signing the payment needs a wallet library, which is what the JavaScript examples are for. The x402 guide walks through the exchange header by header.

As an MCP server

Add the server to any MCP client that takes remote servers. There is nothing to install:

{ "mcpServers": { "cryptoad-network": { "url": "https://cryptoadvertising.net/mcp" } } }

node examples/05-mcp.mjs shows the same thing as raw JSON-RPC: the list of tools, a quote, and the payment requirement a paid tool answers with. The MCP guide describes every tool.

In ElizaOS

ElizaOS connects to remote MCP servers with its own MCP plugin. Add the server to the character's settings:

{
  "plugins": ["@elizaos/plugin-mcp"],
  "settings": {
    "mcp": {
      "servers": {
        "cryptoad-network": {
          "type": "streamable-http",
          "url": "https://cryptoadvertising.net/mcp"
        }
      }
    }
  }
}

That plugin does not sign x402 payments. Give the agent an account that already holds credit: buy credit once with example 02, and have the agent pass the API key as the api_key argument of create_ad. Orders are then paid from the balance. This snippet follows the plugin's documentation; we have not run it inside ElizaOS.

In Coinbase AgentKit

cryptoad-agentkit.ts is an action provider that pays from the agent's own wallet, with the same two guards: only our receiving address, and never more than the cap. Save the file as cryptoad-agentkit.ts in your project (it needs @coinbase/agentkit, @x402/evm, @x402/fetch and zod) and add it to the agent:

import { AgentKit } from "@coinbase/agentkit";
import { cryptoAdActionProvider } from "./cryptoad-agentkit";

const agentkit = await AgentKit.from({
  walletProvider,
  actionProviders: [cryptoAdActionProvider({ maxPaymentUsd: 25 })],
});

It pays with USDC on Base, Polygon or Arbitrum. One real purchase was made through it by calling its actions directly; it has not yet been run by a language model inside an agent.

Rules worth knowing

  • Nothing is created before a payment is confirmed on chain. A quote and a 402 answer create nothing.
  • Repeating a request with the same Idempotency-Key and the same body never pays twice and never places a second ad.
  • An ad that is rejected in review returns its whole budget to the balance. What an ad has not spent returns when it ends.
  • Landing pages must be https. There are no webhooks: poll for the status.

The complete reference is llms.txt for a language model and openapi.json for a program.