DECADocs
decalabs.aiDashboard

Guides

Paid tests

Pay for a test in USDC on Base over x402, and follow it to its result.

Real tests are paid in USDC on Base, for the exact ad budget of the option you pick. Most x402 clients cap a single payment at $1 by default, so raise your client's spend limit before paying for a real test.

To build and try the flow first, use the sandbox: add sandbox: true. It runs the same steps on Base Sepolia for 1 test USDC whatever the budget (free from Circle's faucet); no ads run and progress is simulated.

A test costs its ad budget, nothing more, paid in USDC on Base with x402, the HTTP payment standard. Your agent pays the exact amount the quote names, DECA settles it, and a person reviews the idea before its ads run.

The flow

  1. Quote. Call quote_test and pick an option.
  2. Ask to pay. Call start_test with the quote_id and the option. The answer is 402 Payment Required with an x402 payment request: the exact amount, the USDC contract, the network and DECA's wallet.
  3. Pay. Your x402 client signs the payment and sends the same request again with it in the PAYMENT-SIGNATURE header (over MCP, as the payment argument).
  4. Follow. The answer is 201 with the test and an access_token. Read it with get_test, or give a webhook_url and be told at every change.
import { x402Client } from "@x402/core/client";
import { x402HTTPClient } from "@x402/core/http";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { toClientEvmSigner } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";

const signer = toClientEvmSigner(privateKeyToAccount(process.env.WALLET_KEY as `0x${string}`));
const client = new x402HTTPClient(x402Client.fromConfig({
  schemes: [{ network: "eip155:84532", client: new ExactEvmScheme(signer) }], // eip155:8453 for real tests
  spendControls: { maxAmountPerPayment: "$2000" }, // x402 clients cap a payment at $1 by default
  policies: [(v, reqs) => reqs.filter((r) => r.payTo.toLowerCase() === "0x7fb30ed8d7a7b45ee7b98903d94d87d1b9c3dad2")],
}));

const url = "https://app.decalabs.ai/api/agent/tests";
const body = JSON.stringify({ quote_id, option: "signal", sandbox: true, idempotency_key: crypto.randomUUID() });
const ask = await fetch(url, { method: "POST", headers: { "content-type": "application/json" }, body });
const required = client.getPaymentRequiredResponse((h) => ask.headers.get(h), await ask.json());
const payment = await client.createPaymentPayload(required);
const paid = await fetch(url, { method: "POST", headers: { "content-type": "application/json", ...client.encodePaymentSignatureHeader(payment) }, body });
const { test, access_token } = await paid.json();
Warning

Check payTo before you pay. DECA's wallet is decalabs.base.eth, 0x7FB30eD8D7a7B45EE7b98903d94D87D1B9C3DaD2. A request to pay any other address did not come from DECA.

The payment request

JSON
{
  "x402Version": 2,
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:84532",
    "amount": "1000000",
    "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
    "payTo": "0x7FB30eD8D7a7B45EE7b98903d94D87D1B9C3DaD2",
    "maxTimeoutSeconds": 300,
    "extra": { "name": "USDC", "version": "2" }
  }],
  "deca": { "pay": "$1 test USDC", "budget_usd": 600, "network": "Base Sepolia (sandbox)", "option": "signal", "pass_line": 15 }
}
Real Sandbox
Network Base, eip155:8453 Base Sepolia, eip155:84532
USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 0x036CbD53842c5426634e7929541eC2318f3dCF7e
Charge The option's budget 1 test USDC, whatever the budget
Ads Real, after review None; the test moves through its states in about seven minutes, marked simulated

Safe to retry

  • idempotency_key: send the same one again and you get the same test back, never a second charge. Make it a random value of at least 16 characters and keep it: if the answer to a paid request never reaches you, sending the same request (same payment, same key) again returns the test with a new access_token.
  • A payment that got no answer: the test waits in settling. DECA looks the payment up on Base itself within minutes: paid, it moves to in_review; never paid, it is marked settle_failed and nothing was charged.
  • One payment, one test: a payment that was already used is refused with payment_already_used.
  • Caps hold: with an API key, a test above the key's cap per test (over_cap) or per month (over_month_cap) is refused before any payment is asked for.

The states

State What it means
settling The payment is being settled on Base
in_review A person is reviewing the idea, usually within one business day
building DECA is making the brand, the page and the ads
live The ads are running
reading The ads have ended and the result is being read
done The result is in: pass or miss, confirmed sign-ups against the pass line
declined Declined at review; the whole budget is refunded
cancelled Cancelled before the ads ran; the whole budget is refunded
settle_failed The payment did not go through; nothing was charged

Reading a test

curl -H "Authorization: Bearer deca_sk_…" https://app.decalabs.ai/api/agent/tests/TEST_ID

A test paid with a key also shows in your workspace. A test paid without one is read with the access_token returned once by start_test.

Cancelling

POST /api/agent/tests/TEST_ID/cancel (MCP cancel_test) while the test is in_review. The whole budget is refunded.

Refunds

Declined, cancelled, stopped after its first part, or under budget: the money not spent on ads goes back to the paying wallet, in USDC on Base. get_test shows it under refund: owed, then sent with its transaction.

Webhooks

Send a public https webhook_url with start_test. DECA posts { event, test_id, state, at } at every change, signed in the deca-signature header as sha256= HMAC of the body with the webhook_secret returned once.

Tools

Tool REST What it does
start_test POST /api/agent/tests Ask to pay, then pay and open the test
get_test GET /api/agent/tests/{id} A test's state and everything in it
list_my_tests GET /api/agent/tests Every test paid with your key's workspace
cancel_test POST /api/agent/tests/{id}/cancel Cancel before review ends, with a full refund