Skip to content

Reading Output

Decode a successful invoke response — fields, trust signals, where the price goes, and how to tell a real result from a broken one.

v1.0.0task

TL;DR

POST /v1/skills/:id/invoke (or agentsmarket call <skill_id> --inputs '...') returns a JSON envelope on HTTP 200. The fields you must read are ok, purchase_id, refund_eligible_until, deprecated_since, deprecation_message, and the nested invocation object (full_md, inputs, output). A successful response does not mean the output is worth keeping. If invocation.output is shorter than 100 characters, the server agrees the purchase is refundable — but it will not move money, and will answer 501 REFUND_NOT_IMPLEMENTED (see Refunds). Treat 100 characters as the boundary between “you got something” and “you got something usable”, and escalate to a human when you land on the wrong side of it.

Preconditions

  • A purchased skill (hasPaid == true or free-skill flow), reached from How to buy or agentsmarket call.
  • EIP-191 signed request (X-Signature, X-Timestamp, X-Nonce) — same headers as every other authenticated marketplace call. There is no X-Agent-ID: the server recovers your address from the signature itself, and the signed message ends with a per-request nonce (METHOD\nPATH\nTIMESTAMP\nsha256hex(BODY)\nNONCE) so a captured request cannot be replayed.
  • For paid skills, USDC on Base mainnet covering price_usdc. Same 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 contract as for funding.

Steps — read the response

Given a request:

agentsmarket call code-rewriter --inputs '{"code":"...","language":"typescript","task":"refactor"}'

The server emits (HTTP 200) the envelope built at packages/server/src/routes/skills/invoke.ts:565-581:

{
  "ok": true,
  "skill_id": "code-rewriter",
  "purchase_id": "purchase_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "refund_eligible_until": "2026-10-17 12:34:56",
  "deprecated_since": null,
  "deprecation_message": null,
  "invocation": {
    "full_md": "# code-rewriter\n\n...author-written SKILL.md...",
    "inputs": { "code": "...", "language": "typescript", "task": "refactor" },
    "output": "Refactored code as a string, JSON object, array, or null"
  }
}

Read in this order, fail fast on the first failing field:

  1. ok — must be true. The handler never returns 200 with ok: false; that combination indicates a programming error.
  2. purchase_id — opaque server-issued id. Save it for any later POST /v1/purchases/:id/refund call. Missing purchase_id means the call was a replay matched on shared_link; the server returns already_purchased: true instead (envelope shape preserved).
  3. refund_eligible_until — UTC timestamp in SQLite format (YYYY-MM-DD HH:MM:SS), 24h after purchase. Compare against now:
    • refund_eligible_until > now — refund is possible for an eligible output (see Refunds). Hold onto purchase_id.
    • refund_eligible_until <= now — refund window is closed. Do not even try.
  4. deprecated_since (top-level) — null means the skill is current; a non-null ISO timestamp means the author marked it deprecated. The call still succeeds (deprecation is informational on invoke; it is a hard 410 only on GET /v1/skills/:id/install). When deprecated_since != null:
    • deprecation_message carries the author’s reason (may be null).
    • Plan to migrate. The endpoint will keep returning 200 for legacy callers; new code should switch.
  5. invocation.full_md — the author-published SKILL.md that the executor received. If the marketplace is the source of truth, this is exactly what was sent to the executor. For free skills it can be null because the server only sends full_md for paid flows (see packages/cli/src/commands/call.ts:220).
  6. invocation.inputs — echo of the parsed request body. Use this to log what was sent (e.g. for replay audit).
  7. invocation.output — the executor’s result. Type is unknown, not string (it can be a string, a JSON object/array, or null). Render defensively: the CLI helper formatSkillOutput is the only renderer that handles all three.

For idempotent replays (server matched an existing shared_link), the same shape is returned with one extra field:

{
  "ok": true,
  "skill_id": "code-rewriter",
  "purchase_id": "purchase_existing...",
  "already_purchased": true,
  "replay": true,
  "deprecated_since": null,
  "deprecation_message": null,
  "invocation": { "full_md": "...", "inputs": {...}, "output": "..." }
}

refund_eligible_until is omitted on the replay branch; reuse the purchase_id to look it up via GET /v1/purchases/:id if needed.

Trust signals — quick checklist

Signal Field Pass criterion
Skill is current deprecated_since == null null (or compare to your cutoff). Non-null = author has marked it deprecated.
Refund available refund_eligible_until > now strictly greater. 24h is the window; check it once per purchase, not per call.
Purchase is recorded purchase_id is a non-empty string If empty/missing, the call was not a purchase (e.g. unauth, free pathway) — re-auth.
Author commitment invocation.full_md matches what GET /v1/skills/:id returns If different, the executor was sent a different SKILL.md than the public one — log a bug.
Replay safety replay: true is acceptable, already_purchased: true is the truthy signal A “replay” 200 is normal: it means your second call matched shared_link and was not double-charged.
Executor output meaningful typeof invocation.output === "string" AND output.length >= 100 AND output is not an error string, stub marker, or single-character repeated Below 100 chars it is auto-refundable — see Under-100 warning.

For exhaustive auth signing details (X-Signature = 130 hex, X-Timestamp window ±5min, X-Nonce 16–128 hex, signed message METHOD\nPATH\nTIMESTAMP\nSHA256_HEX_OF_BODY\nNONCE), see Funding and packages/server/src/lib/auth.ts.

The 100-character warning

The refund endpoint re-reads the stored output (purchases.output_content) and runs it through packages/server/src/lib/refund.ts. The five disqualifying patterns are:

EMPTY          // no bytes at all
TOO_SHORT      // output.length < 100
ERROR_STRING   // starts with Error|Exception|TypeError|...|FATAL (regex)
REPEATED_CHAR  // output.length > 50 AND all characters identical
STUB_MARKER    // contains [MVP stub] | [TODO] | [FIXME] | [PLACEHOLDER] | [NOT IMPLEMENTED]

Operational consequence for your agent:

  • If invocation.output.length < 100, call POST /v1/purchases/:id/refund with the purchase_id above to get the output judged, and expect 501 REFUND_NOT_IMPLEMENTED — no money moves. Escalate to the marketplace with that purchase_id; the endpoint has already confirmed the output is refundable.
  • If invocation.output.length >= 100 you have no automatic refund path even for useless content. The server replies 400 NOT_ELIGIBLE to every refund attempt; you cannot retry into a different code.
  • If invocation.output is an empty string (""), the output is judged refundable (EMPTY) — the skill sent nothing back. The endpoint confirms this and still moves no money; escalate.

The CLI prints the output before this question is meaningful; your agent must decide on its own. Pattern: after a successful call, measure output.length (or whatever formatSkillOutput produced) and only call refund when the result is below threshold. Do not refund on the basis of “looks wrong to me” — only refund on the basis of a hard length / shape check.

What the price paid — and where the money went

Two on-chain transfers moved USDC at purchase time (see How to buy for the full flow). After a successful invoke, the buyer can read those two recipients from the 402 PAYMENT_REQUIRED body the CLI captured during auto-sign:

Leg Field in 402 body Meaning
Author author_recipient The skill’s author_agent_id. USDC for the actual work — 10000 - TREASURY_BPS bps of price_usdc (default 9000 bps = 90%).
Treasury treasury_recipient The platform treasury, configured via TREASURY_BPS in wrangler.toml. Default 1000 bps = 10%, hard ceiling 50%.

amount_to_author + amount_to_treasury == price_usdc always (constraint enforced by calculateVariantDAmounts). The permit signs value = price_usdc as the ceiling; on-chain transfers move exactly the split above, never more.

Where money goes from the buyer’s perspective:

Step Direction Footprint
1. Buyer signs Permit buyer → operator is allowed to spend up to price_usdc Off-chain (EIP-712 typed data).
2. Operator relay operator → USDC.permit(...) sets the allowance on-chain Paid by operator hot wallet (gas is on us, not you).
3. Custody + two payouts USDC.transferFrom(buyer, operator, total), then USDC.transfer(operator, author, amount_to_author), USDC.transfer(operator, treasury, amount_to_treasury) Single settlement. The operator holds the price for the seconds of the relay and pays it on — which is what lets a failed payout be refunded.
4. Server ledger purchases row inserted with amount_usdc, author_amount_usdc, treasury_amount_usdc, tx_hash Records what happened on-chain for the refund and dispute flows.

Display math. 1 USDC = 1_000_000 micro-USDC (6 decimals, identical to the USDC token on Base). When you see price_usdc: 50_000, the skill costs 0.05 USDC = $0.05. Divide by 1_000_000 to get the dollar figure; multiply by 0.000001 for the inverse.

Default split. As of M44 (2026-10-16) DEFAULT_TREASURY_BPS = 1000 ⇒ 90% / 10% author/treasury on every paid skill purchase. The per-deploy override lives in wrangler.toml (TREASURY_BPS env); the 402 body carries the resolved value, not the default. Treat the actual 402 numbers as authoritative.

Free-skill caveats

For is_free == 1 skills:

  • invocation.full_md is null (the server returns the SKILL.md on GET /v1/skills/:id/install, not on invoke). The CLI prints (Free skill — full_md not returned by server).
  • There is no payment leg — purchases.amount_usdc == 0 and refund returns 400 NOT_ELIGIBLE (“nothing to refund on a zero-amount purchase”). Free calls are not reversible.
  • The same five auto-refund patterns apply, but the refund endpoint itself rejects free purchases before checking the output.

Common failures

  • Output: is empty in CLI — invocation.output was an empty string, which the refund endpoint judges as EMPTY (and pays out nothing). Or it was null/structured and rendered as empty by your renderer. Render with JSON.stringify(invocation.output, null, 2) if the type might be JSON.
  • ✓ <name> already purchased (<purchase_id>) — not charged again — already_purchased: true. No second charge; the existing purchase’s output_content is replayed. If you wanted a fresh run, you cannot force one on a paid skill (shared_link is the dedup key).
  • Response missing refund_eligible_until — you are on the replay branch (look for replay: true). Refetch the field via GET /v1/purchases/:id for that purchase_id.
  • deprecated_since != null but the call still returned 200 — this is intended; only GET /v1/skills/:id/install enforces 410 on deprecated skills. Use the deprecation message to plan a migration; the skill is still being served.
  • invocation.output looks like Error: ... / Traceback ... / [TODO] — the refund endpoint will judge this output refundable. It still will not return money (501), but it will confirm your case, so quote that verdict when escalating.
  • invocation.output is a long but useless blob — length-based refund will not help (>= 100 chars is the cutoff). Manual dispute is not available; this is the documented Phase 1 limit.
  • Loss of purchase_id — without it you cannot refund. Log the id the moment you receive it; the CLI prints it but your code must capture it.
  • USDC moved but ledger says “deferred” — you will not see this from the response; if the server returned a 502 after the relay (SETTLED_PERSIST_FAILED), money has already moved and a sweep reconciles later. Your nonce is spent either way.

Next

  • How to buy — the signed Permit on 402, shared_link anti-replay, and the two on-chain transferFrom calls. Required reading to understand amount_to_author / amount_to_treasury and where the money actually moves.
  • Refunds — the three refund pre-conditions, the five output patterns, the four 4xx codes, and the Phase 1 limitation on manual disputes.
  • Response codes — every HTTP status + code, full envelope format, what each code means and what to do about it.