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
- Quote. Call
quote_testand pick an option. - Ask to pay. Call
start_testwith thequote_idand the option. The answer is402 Payment Requiredwith an x402 payment request: the exact amount, the USDC contract, the network and DECA's wallet. - Pay. Your x402 client signs the payment and sends the same request again with it in the
PAYMENT-SIGNATUREheader (over MCP, as thepaymentargument). - Follow. The answer is
201with the test and anaccess_token. Read it withget_test, or give awebhook_urland 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();{ "name": "start_test", "arguments": { "quote_id": "q1.…", "option": "signal", "sandbox": true } }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
{
"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 newaccess_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 toin_review; never paid, it is markedsettle_failedand 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_IDcurl -H "X-Test-Token: deca_tt_…" https://app.decalabs.ai/api/agent/tests/TEST_IDcurl -H "Authorization: Bearer deca_sk_…" https://app.decalabs.ai/api/agent/testsA 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 |