Decide: execute a plan

Run a decision's plan through Agent402: first-party steps run directly, third-party steps are bought from the seller and resold to you (you pay on Base, or by credits or card) at the seller's price plus a disclosed markup. Send POST /api/decide/execute with no required fields (5 optional) and pay quoted per request from $0.001 over x402 with USDC on Base. It returns a JSON object with runId, decisionId, status, steps, budgetUsd and 5 more.

Priced at the plan's budget (or your maxBudgetUsd, whichever you set) less a valid execution credit; spend stops at that budget, fallbacks are tried in order, and any unspent amount comes back as a credit. A run where no step succeeds is not charged. Also runs a free plan sketch: pass the sketch's tool slugs as steps (no decisionId) with params for step 1, and each later step takes its one required input from the step before, at list price. Takes up to 3 minutes to answer: keep the connection open for at least 210 seconds, because a client that disconnects first loses the answer, or send the paid call with "Prefer: respond-async" to get a job link at once and collect the answer from it (payment still settles only on a delivered result).

Category: Routing & delegation · Tags: agents execute planning router x402

TRY IN PLAYGROUND →

Parameters

Example request

curl -i -X POST https://agent402.tools/api/decide/execute \
  -H "Content-Type: application/json" \
  -d '{"decisionId":"dec_2b1c9e0f4a7d4c3e9b8a1f00","creditToken":"dc_...","maxBudgetUsd":0.05}'

Without payment this returns HTTP 402 Payment Required with the exact price for decide-execute; any x402 v2 or MPP client pays it and retries.

Example response

{
  "runId": "run_…",
  "decisionId": "dec_…",
  "status": "complete",
  "steps": [
    {
      "step": 1,
      "status": "ok",
      "tool": {
        "slug": "search",
        "seller": "agent402",
        "firstParty": true
      },
      "costUsd": 0.02,
      "result": {}
    }
  ],
  "budgetUsd": 0.02,
  "spentUsd": 0.02,
  "paidUsd": 0.001,
  "creditAppliedUsd": 0.02,
  "routingFeePct": 5,
  "leftoverCredit": null
}

From an MCP client

catalog.call {
  "slug": "decide-execute",
  "params": {
    "decisionId": "dec_2b1c9e0f4a7d4c3e9b8a1f00",
    "creditToken": "dc_...",
    "maxBudgetUsd": 0.05
  }
}

The hosted connector at https://agent402.tools/mcp needs a payment for decide-execute; the stdio package pays it from a wallet or from AGENT402_CREDITS_KEY. Local install: npx -y agent402-mcp.

Errors and behavior

• Every field is optional. An input the tool rejects returns an HTTP 4xx whose body carries error, tool, expected, required and example.
• A paid call that ends in any status of 400 or above is not charged over x402, MPP or a prepaid credits key: settlement is cancelled when the tool fails.
• Wallet-only: this tool runs a model, so it has no proof-of-work tier. A prepaid card-credits key issued earlier (Authorization: Bearer a402_...) also pays it.
• Model-backed: the answer is generated by a model, so the same input can produce different wording.
• Long-running: payment settles after the work finishes, so only EVM exact payments are offered.
• Takes up to 180 seconds. Keep the connection open that long, or send the paid call with Prefer: respond-async to get 202 and a job link at once, then collect the answer from GET /api/jobs/{id}; payment still settles only when the answer is ready.
• Priced per request: the 402 quotes this body, between $0.001 and $3.
• A GET or HEAD to /api/decide/execute returns the same 402 quote, so the price can be read without a body.
• An Idempotency-Key header makes a retried paid call replay the first 200 instead of charging again (an answer larger than 1 MB is not replayed).

Paid call (JavaScript agent)

import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const client = new x402Client();
client.setSpendControls?.(false); // keep your own spending ceiling in code
registerExactEvmScheme(client, { signer: privateKeyToAccount(KEY) });
const payFetch = wrapFetchWithPayment(fetch, client);

const res = await payFetch("https://agent402.tools/api/decide/execute", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    "decisionId": "dec_2b1c9e0f4a7d4c3e9b8a1f00",
    "creditToken": "dc_...",
    "maxBudgetUsd": 0.05
  }),
});

Related tools