Agent quickstart

Unstuck for agents

Agent summary

What: Unstuck explains Solana transactions: what happened, what it cost, what to do next, plus a fix an agent can apply.

Call: GET https://www.unstucksol.com/api/explain?sig=<signature>, or POST the same URL with {"signature":"<base58>"}. Live on mainnet.

Catalog: GET https://www.unstucksol.com/api/errors?q=<text>: raw error, decoded, plain words, typical fix.

Price: Free during the beta, no key, no account. Beta: calls are free; the x402 flow is the planned paid tier and is not enforced.

Install: Use the HTTP API today (curl / fetch); the MCP server and skill package ship when the API leaves beta. The skill file is at https://www.unstucksol.com/agents/SKILL.md.

Rules: Apply fix only when fix.safe is true. Retry at most twice. Otherwise stop and ask a person. Never sign anything Unstuck returns: it returns parameters, not transactions.

Files: llms.txt · agents/SKILL.md · agents/openapi.yaml · agents/mcp.json (planned) · docs.html

How an agent uses it

The self-healing loop

Your agent explains its own failed transaction, applies the fix when it’s safe and stops before it can make things worse.

  1. 01

    The transaction fails

    Your agent has a signature and an error it can’t act on.

    custom program error: 0x1771
  2. 02

    It calls explain

    One GET with the signature, free during the beta. The answer has the decoded error and a fix.

    GET /api/explain?sig=…
  3. 03

    It applies the fix if it’s safe

    Only when fix.safe is true and the action is within its mandate. The fix is parameters, never a transaction.

    fix.safe → slippage_bps: 100
  4. 04

    It retries, at most twice

    Still failing after two retries? It stops.

    retry ≤ 2

  5. No safe fix means stop. When fix.safe is false or there is nothing to fix, the agent stops and asks a person, with the plain answer and the chain context attached.

The loop in code
// Self-healing with Unstuck. It returns parameters; your agent builds and signs.
const explain = async (sig) =>
  (await fetch("https://www.unstucksol.com/api/explain?sig=" + sig)).json();

let sig = await send(tx);                      // signed with your agent's own key

for (let retries = 0; !(await succeeded(sig)); retries++) {
  const r = await explain(sig);                // free during the beta, no key

  if (r.handoff || !r.fix?.safe || retries === 2) {
    await askAPerson(r);                       // plain words + chain context
    break;
  }

  tx = applyFix(tx, r.fix);                    // { action: "retry", params: { slippage_bps: 100 } }
  sig = await send(tx);
}

Install

Use the HTTP API today

Use the HTTP API today (curl / fetch); the MCP server and skill package ship when the API leaves beta. Every call below works now, with no key.

  • curl

    A real failed swap on mainnet. Paste it into a terminal.

    curl 'https://www.unstucksol.com/api/explain?sig=3cbDDFD5GrPVzJZCfP8ppSGiTFHd6RHQBbgkrgRpXLbu2fbSPdKdgjimJduvMhRP3N8yh6QznSmtSVbh3feUwV2R'

  • fetch

    From an agent, a script or the browser console.

    const answer = await (await fetch("https://www.unstucksol.com/api/explain?sig=" + sig)).json();

  • Error catalog

    Look up a raw error your agent keeps seeing.

    curl 'https://www.unstucksol.com/api/errors?q=0x1771'

  • Skill file

    For any agent that reads SKILL.md: when to call, the rules, the live HTTP calls. Read it

    https://www.unstucksol.com/agents/SKILL.md

Price per call

Free during the beta.

No key, no account, no sign-in. Paid plans open later.

  • explainGET /api/explainFree in beta
  • errorsGET /api/errorsFree
  • Beta: calls are free; the x402 flow is the planned paid tier and is not enforced.
  • Planned price: 0.10 USDC per explain call, paid over x402. The catalog stays free.
  • Roughly 30 explain lookups a minute per IP address; answers are cached for 5 minutes.

Planned

x402: ask, pay, get the answer

Beta: calls are free; the x402 flow is the planned paid tier and is not enforced. When it is, the first answer will be a price your agent pays in USDC on Solana, with no account and no key.

What your agent will check before paying

  • amount is "100000": 0.10 USDC, which has 6 decimals.
  • asset is the USDC mint EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v.
  • network is Solana mainnet, solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp.
  • Keep X-PAYMENT-RESPONSE. It will be the settlement transaction, the receipt.
The planned flow, step by stepNot enforced in the beta

01Ask. The answer is a price.

HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: {"scheme":"exact","network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
  "asset":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","amount":"100000",
  "payTo":"<address>","resource":"https://www.unstucksol.com/api/explain"}

02Pay 0.10 USDC and send it again.

X-PAYMENT: <signed USDC transfer, base64>

03Get the answer and the receipt.

HTTP/1.1 200 OK
X-PAYMENT-RESPONSE: <settlement tx signature>

Discovery

Files your agent can read

Static files, no key needed. Point your agent at llms.txt first: it links to everything else.

Unstuck never holds keys, never signs and never moves funds.

Read the security model