Score Ads From Your AI Agent

How it works

The endpoint speaks x402 — the open "HTTP 402 Payment Required" standard that lets software pay for a single request with stablecoins. There are no accounts to create and no keys to manage. The flow is three steps your agent's wallet SDK handles automatically:

1. Your agent POSTs the ad to the endpoint. With no payment attached, it gets back 402 Payment Required describing the price and the accepted payment options.
2. The wallet SDK signs a $5 USDC payment and retries the request with the payment attached.
3. The server verifies and settles the payment, then queues the scoring job and returns a job id plus a free status URL to poll for the result.

Endpoint & pricing

Quick start (Node / TypeScript)

The x402-fetch wrapper turns the whole 402 → pay → retry dance into a normal fetch call. Point it at a wallet that holds USDC on Solana or Base:

import { wrapFetchWithPayment } from "x402-fetch";
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { base } from "viem/chains";

// A wallet funded with a little USDC on Base (or use a Solana signer)
const account = privateKeyToAccount(process.env.PRIVATE_KEY);
const wallet = createWalletClient({ account, chain: base, transport: http() });

const fetchWithPay = wrapFetchWithPayment(fetch, wallet);

// 1) Submit the ad — payment is handled automatically on the 402
const res = await fetchWithPay("https://pretestads.com/api/v1/score", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    media_url: "https://example.com/my-ad.mp4",
    window_seconds: 15,
  }),
});

const { id, status_url } = await res.json();

// 2) Poll the free status endpoint until the score is ready (~5-8 min)
let result;
do {
  await new Promise((r) => setTimeout(r, 20000));
  result = await (await fetch(status_url)).json();
} while (result.status !== "complete" && result.status !== "failed");

console.log(result.score, result.label, result.verdict);

What a request looks like

Send JSON with a public media_url, or a multipart upload with a file field. An unpaid request returns the payment options:

$ curl -X POST https://pretestads.com/api/v1/score \
    -H "Content-Type: application/json" \
    -d '{"media_url":"https://example.com/my-ad.mp4"}'

HTTP/1.1 402 Payment Required
{
  "x402Version": 2,
  "accepts": [
    { "scheme":"exact", "network":"solana:5eykt4...", "amount":"5000000",
      "asset":"EPjFWdd5...USDC", "payTo":"<merchant Solana address>" },
    { "scheme":"exact", "network":"eip155:8453", "amount":"5000000",
      "asset":"0x8335...USDC", "payTo":"<merchant Base address>" }
  ]
}

What you get back

Once scoring completes, the status URL returns the full result — a 0-100 attention score benchmarked against 76 top-performing TikTok Creative Center ads, a label, a plain-language verdict, and a per-second engagement curve:

{
  "id": "4c28e9c0-...",
  "status": "complete",
  "score": 79,
  "label": "strong",
  "verdict": "Your ad outperforms the majority of TikTok's top performers...",
  "engagement_timeseries": [
    { "second": 0, "activation": 0.25 },
    { "second": 1, "activation": 0.06 },
    ...
  ]
}

Notes for agent builders

• One payment, one score. Each settled payment buys exactly one scoring run. Re-sending the same payment proof is rejected.
• Settlement happens first. The payment is confirmed on-chain before the job runs, so a valid request always produces a job.
• Discoverable. The endpoint publishes an x402 Bazaar discovery schema, so agents that browse the Bazaar catalog can find it and read its input/output shape automatically.
• Machine-readable docs. A summary for agents lives at /llms.txt.