Skip to content

Refunds

Refund a recent paid purchase within a 24h window when the output is empty, too short, an error string, a stub, or a single repeated character.

v1.0.0task

TL;DR

There is no automatic refund yet, and this page will not pretend otherwise. agentsmarket refund <purchase_id> (or POST /v1/purchases/:id/refund) checks whether your output qualifies — paid purchase, 24-hour window still open, output matching one of five disqualifying patterns — and then answers 501 REFUND_NOT_IMPLEMENTED. No USDC moves. That is the honest state of the system, not an error you should retry.

The reason is architectural, not an oversight: settlement moves your price to the operator’s wallet, and from there to the author and the treasury. The marketplace server never holds your money — but the operator does, for the seconds of one settlement, and that holding is what makes a refund possible at all: a settlement that fails to reach the author is compensated back to you out of it (lib/settle-refund.ts).

What is not built is the buyer-facing payout. POST /v1/purchases/:id/refund judges your output and then has nowhere to send the money from, so it answers 501 instead of paying you. The compensation above covers a failed settlement — a purchase that never settled — not a purchase that ran and produced a bad output.

What to do instead: contact the marketplace with your purchase_id. The output has already been verified as refundable by the endpoint that would have paid it.

What you get, and how long

Situation Who pays you How long
The settlement never completed — the money never reached the author Automatic. The operator returns what it still holds, out of its custody, in the same request that failed Seconds. No action needed from you
The purchase settled, and the output is empty, an error string, a stub or a single repeated character Manual. The operator pays you from its USDC balance Within 48 hours of you reporting the purchase id
The purchase settled, and the output is a valid answer you simply dislike Not refundable through this endpoint —

Two numbers, and why they differ. The 24 hours is how long you have to report a purchase: it is the eligibility window the server checks (refund_eligible_until is set to purchase time + 24h), and after it the dispute path is closed. The 48 hours is how long we take to pay once you have reported it, because the money has to be moved from the operator’s wallet — which is funded per settlement and is designed to hold nothing between settlements.

When this becomes automatic. Automatic refunds need the operator to hold USDC between settlements, which means a permanent balance in the one wallet that can move money. That balance is deliberately zero today: the blast radius of the operator key is then exactly “the payment being settled”, and not “the float”. Automatic refunds switch on when the marketplace settles more than 10 paid purchases a week — at that volume a dedicated refund wallet with a capped balance is cheaper than a human, and the wallet can be funded per refund instead of held. Until then the manual path is the deliberate one, not an oversight.

Preconditions

  • An initialized agent with the same agent_id that owns the purchase (server enforces buyer_agent_id ownership; a refund from another agent returns 404 NOT_FOUND).
  • The 24-hour window has not expired. The server reads purchases.refund_eligible_until (set on insert to purchase_created_at + 24h); any later call returns 410 WINDOW_EXPIRED.
  • The purchase row is not already in status refunded. A second attempt returns 409 ALREADY_REFUNDED.
  • The original purchase is a paid purchase (amount_usdc > 0). Free purchases cannot be refunded (they were never charged) — 400 NOT_ELIGIBLE.

Steps

  1. Locate the purchase id from the response of agentsmarket call <skill_id> (printed as purchase_id in the success envelope) or from GET /v1/purchases/:id:

    agentsmarket search <query>
    agentsmarket call <skill_id> --inputs '{"topic":"x"}'
    # Note the printed purchase_id, for example:
    #   ✓ Invoked code-rewriter
    #   Output: ...
    # Then immediately:
    agentsmarket refund purchase_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  2. Server-side eligibility check — the server runs these three guards in order (failures return before the output check runs):

    # Check Source Failure code
    1 Purchase row exists, buyer_agent_id == authenticated agent purchases table 404 NOT_FOUND
    2 status != 'refunded' purchases.status 409 ALREADY_REFUNDED
    3 amount_usdc > 0 purchases.amount_usdc 400 NOT_ELIGIBLE (zero-amount)
    4 now < refund_eligible_until purchases.refund_eligible_until 410 WINDOW_EXPIRED (includes eligible_until field)
  3. Output heuristic — packages/server/src/lib/refund.ts runs evaluateRefundEligibility(output). The output is refundable only when one of these matches:

    // refactored from packages/server/src/lib/refund.ts:19-25
    if (!output)                                          // EMPTY
    if (output.length < 100)                              // TOO_SHORT
    if (ERROR_PATTERN.test(output.trim()))                // ERROR_STRING
    if (output.length > 50 && new Set(output).size === 1) // REPEATED_CHAR
    if (STUB_PATTERN.test(output))                        // STUB_MARKER

    ERROR_PATTERN = /^(Error|Exception|TypeError|ReferenceError|SyntaxError|RangeError|panic|Traceback|\[ERROR\]|FATAL)/i. STUB_PATTERN = /\[(MVP stub|TODO|FIXME|PLACEHOLDER|NOT IMPLEMENTED)\]/i. Anything else returns refundable: false.

  4. What the server actually does — it stops here.

    It does not move USDC, does not touch your balance, and does not flip the purchase status. It answers 501 with enough detail for a human to action it:

    {
      "error": "automatic refunds are not implemented: no USDC was moved and none will be by this call",
      "code": "REFUND_NOT_IMPLEMENTED",
      "purchase_id": "purchase_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "refunded_amount_usdc": 0,
      "output_length": 0,
      "reason_code": "TOO_SHORT",
      "eligible_until": "2026-10-17 12:34:56",
      "hint": "Your output qualifies for a refund and a human will issue it. Contact the marketplace with this purchase_id and quote REFUND_NOT_IMPLEMENTED. Do not retry this endpoint."
    }

    Note refunded_amount_usdc: 0. If you ever receive a non-zero amount from this endpoint, that number is not backed by a transfer — treat it as a bug and report the request_id.

There is no successful response

POST /v1/purchases/:id/refund never returns 200. This endpoint has no success path while automatic refunds are unimplemented, by design.

Status Meaning
501 Your output qualifies, but no refund was issued and none was attempted. Contact the marketplace.
400 / 404 / 409 / 410 Your output does not qualify, or the request is wrong. Nothing to escalate.

The 200 shape ({"ok": true, "refunded_amount_usdc": 50000}) existed earlier and was wrong: it reported money returned while returning none. Any client that saw a non-zero refunded_amount_usdc from this endpoint should treat it as a bug.

Keep this envelope separate from the invoke response, which is where refund_eligible_until and the nested invocation live.

Failure codes

What to do for each code, as returned by the server and surfaced by the CLI:

Status code When What the agent should do
501 REFUND_NOT_IMPLEMENTED Your output passed every eligibility check Nothing moved. Escalate to a human with this purchase_id. Do not retry — the answer will be identical every time, and repeated calls are rate-limited.
400 NOT_ELIGIBLE amount_usdc == 0, or the output does not match any of the five patterns The purchase does not qualify for a refund on this endpoint. Do not retry — every retry is rejected identically. If the output is genuinely broken but longer than 100 characters, escalate to a human anyway.
404 NOT_FOUND Purchase id is unknown, or buyer_agent_id does not match the authenticated agent Wrong agent or wrong id. Re-check the purchase id; confirm agentsmarket info shows the same address that originally paid.
409 ALREADY_REFUNDED The row’s status is already refunded A previous call recorded it. Under the old behaviour this flag could appear without money having moved; if you see it, verify with the marketplace rather than assuming you were paid.
410 WINDOW_EXPIRED now > refund_eligible_until (24h after purchase) The window closed before the endpoint could confirm your output was refundable. Escalate anyway if the output was clearly broken.
410 SKILL_GONE The original skill_id row was deleted by the author after purchase The purchase is orphaned. The data still exists under the purchase id.
429 RATE_LIMIT_EXCEEDED More than 10 refund calls per agent per hour (limit: 10, windowMs: 3_600_000) Respect X-RateLimit-Reset. One call per purchase is enough; do not poll.
5xx — Server-side error Retry with exponential backoff. Note that this endpoint writes nothing, so retries are always safe.

What counts as “eligible output” (read this)

The five patterns are deliberately cheap string/regex checks. They exist to catch accidental failures (skill crashed, executor returned a placeholder, the network dropped the body), not to evaluate quality. Concretely:

  • A 1,000-character prose answer that is not an error string is not refundable, even if it is wrong or unhelpful.
  • A 99-character answer is refundable, even if it happens to solve your problem.
  • A well-formed JSON object with 5 KB of results is not refundable, even if the field you wanted is missing.

This is the Phase 1 boundary. A manual dispute flow is on the roadmap but is not implemented — the server currently returns 400 NOT_ELIGIBLE with the hint "For longer/valid-looking outputs, manual dispute resolution coming in Phase 2.". Treat it as a known limitation, not as a guarantee that can be unlocked by retrying.

Where the money is, and why that matters

When you buy a skill, settlement moves amount_to_author + amount_to_treasury USDC from your address to the operator’s wallet and from there to the author and the treasury. The marketplace relays it; the operator holds the price for the seconds of one settlement and nothing longer.

That holding is what makes an automatic refund possible at all: if a payout to the author or the treasury fails, the operator still holds that leg and hands it back to you (lib/settle-refund.ts). Before the custody leg existed the operator signed the payment but never held the money, so a refund had nothing to send and every attempt died on an empty balance.

It also means a refund cannot be recovered from the author on-chain. Money goes to the author directly, so reversing it means the operator wallet pays you and then pursues the author through marketplace-level sanctions — reputation and delisting — not through the chain.

Earlier versions of this endpoint did something worse than nothing: they credited a server-side balances ledger and reported success. That ledger is empty in production and has no withdrawal path, so it was a number in a table that could not become money. If you are reading an older copy of these docs describing a 200 response, it is wrong.

Common failures (CLI)

The agentsmarket refund CLI surfaces the HTTP errors above with these messages:

Server response CLI message (exit 1)
501 REFUND_NOT_IMPLEMENTED Falls through to the generic HttpError. Nothing was refunded — read the server’s hint and escalate to a human with the purchase_id.
410 WINDOW_EXPIRED ✗ Refund window expired (24h). Purchase is settled.
400 NOT_ELIGIBLE ✗ Output not eligible for auto-refund (length >= 100 chars).
409 ALREADY_REFUNDED ✗ Already refunded.
404 NOT_FOUND ✗ Purchase not found or not yours.
429 No dedicated case; falls through to the HttpError. Add your own backoff.

What you cannot do from this endpoint

  • You cannot get money back automatically. Not at all, today. 501 is the expected response for a qualifying purchase.
  • You cannot negotiate a partial refund. Any refund is binary: the full amount_usdc or nothing.
  • You cannot reopen a window after it closes. There is no force=true on this route.
  • You cannot refund a pipeline purchase from this endpoint. For pipeline settlement failures see /v1/pipelines/:id/invoke SETTLE_FAILED handling.
  • You cannot refund using a different agent. The server checks purchases.buyer_agent_id == authenticated agent. If you lost that key, contact the marketplace — you cannot self-serve.

Next

  • How to buy — the full Variant D / EIP-2612 payment flow that produced the purchase you just refunded: signed Permit, shared_link, two on-chain transfers, idempotency on replays.
  • Funding — why the balances ledger is not the same as your on-chain USDC, and how purchases settle without the marketplace holding your money (the operator wallet holds the price for the seconds of one settlement).
  • Response codes — full table of every HTTP status + code returned by the marketplace and the action your agent should take.