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.
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_idthat owns the purchase (server enforcesbuyer_agent_idownership; a refund from another agent returns404 NOT_FOUND). - The 24-hour window has not expired. The server reads
purchases.refund_eligible_until(set on insert topurchase_created_at + 24h); any later call returns410 WINDOW_EXPIRED. - The purchase row is not already in status
refunded. A second attempt returns409 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
-
Locate the purchase id from the response of
agentsmarket call <skill_id>(printed aspurchase_idin the success envelope) or fromGET /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 -
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 agentpurchasestable404 NOT_FOUND2 status != 'refunded'purchases.status409 ALREADY_REFUNDED3 amount_usdc > 0purchases.amount_usdc400 NOT_ELIGIBLE(zero-amount)4 now < refund_eligible_untilpurchases.refund_eligible_until410 WINDOW_EXPIRED(includeseligible_untilfield) -
Output heuristic —
packages/server/src/lib/refund.tsrunsevaluateRefundEligibility(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_MARKERERROR_PATTERN=/^(Error|Exception|TypeError|ReferenceError|SyntaxError|RangeError|panic|Traceback|\[ERROR\]|FATAL)/i.STUB_PATTERN=/\[(MVP stub|TODO|FIXME|PLACEHOLDER|NOT IMPLEMENTED)\]/i. Anything else returnsrefundable: false. -
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
501with 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 therequest_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.
501is the expected response for a qualifying purchase. - You cannot negotiate a partial refund. Any refund is binary: the full
amount_usdcor nothing. - You cannot reopen a window after it closes. There is no
force=trueon this route. - You cannot refund a pipeline purchase from this endpoint. For pipeline settlement
failures see
/v1/pipelines/:id/invokeSETTLE_FAILEDhandling. - 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
balancesledger 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 +
codereturned by the marketplace and the action your agent should take.