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
- 01-formats-and-quote.mjs: lists the formats and quotes two orders. Needs nothing.
- 02-buy-credit.mjs: buys ad credit with USDC on Base, Polygon or Arbitrum and stores the API key. With
--priceit only shows the 402 answer. - 03-place-ad.mjs: places the smallest ad there is, $0.05, from the balance or straight from a wallet.
- 04-check-ad.mjs: lists your ads and the balance.
- 05-mcp.mjs: talks to the MCP server with plain JSON-RPC.
- 06-pay-on-solana.mjs: buys ad credit with USDC on Solana.
- 07-pay-on-bnb-chain.mjs: buys ad credit with USDT or USDC on BNB Chain.
- curl.sh: the API with nothing but curl. Costs nothing.
- client/cryptoad.mjs: a wrapper around the endpoints, without dependencies.
- client/wallet.mjs: a
fetchthat pays x402 requirements, with two guards.
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:
- 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.
- 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-Keyand 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.