---
name: unstuck
description: Explain a Solana transaction in plain words — what happened, what it cost, what to do next — and get a concrete fix (retry with settings, add a little SOL, use the right token account). One HTTP call, live on mainnet, free during the beta, no key.
version: 0.1.0
homepage: https://www.unstucksol.com
---

# Unstuck skill

## When to use
- Your own transaction failed or landed with an unexpected result: call `explain` with the signature before retrying blindly.
- A user pastes a signature or says "my swap failed / my tokens are gone": call `explain` and relay the plain-words answer and the fix.
- You keep seeing the same raw error: look it up with `errors` (the public catalog).

## Tools (live HTTP endpoints)
| Tool | HTTP, live today | Price |
|---|---|---|
| `explain(signature)` | `GET https://www.unstucksol.com/api/explain?sig=<signature>` · or `POST /api/explain` with `{"signature":"..."}` | free in beta |
| `errors(query?)` | `GET https://www.unstucksol.com/api/errors?q=<text>` | free |
| `unstuck.explain`, `unstuck.errors` (MCP) | **Planned**: the same two calls as MCP tools, when the API leaves beta | — |

No key, no account, no sign-in. `sig` takes a base58 signature or an explorer link with `/tx/<signature>`. Mainnet only.

## Install
Use the HTTP API today (curl / fetch); the MCP server and skill package ship when the API leaves beta.

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

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

## Response shape (real answer, logs trimmed)
```json
{"signature":"3cbDDFD5GrPVzJZCfP8ppSGiTFHd6RHQBbgkrgRpXLbu2fbSPdKdgjimJduvMhRP3N8yh6QznSmtSVbh3feUwV2R",
 "status":"failed","title":"Slippage limit exceeded","program":"Jupiter v6","via":null,
 "raw_message":"custom program error: 0x1771","decoded":"SlippageToleranceExceeded (6001)",
 "plain":"The price moved more than your slippage limit allowed, so the swap was cancelled.",
 "cost":{"sol":0.00002191,"note":"Network fee only (incl. 0.00001691 SOL priority fee). Nothing was swapped or sent."},
 "fix":{"action":"retry","params":{"fresh_quote":true},"safe":true},
 "handoff":false,"slot":456949936,"fee_payer":"4B8srvotmWddTZuMt4RrBQrnx1sQj2Z7FaXgLbWvpVdd"}
```
- `status`: `failed` | `succeeded` | `not_found` (not found comes back as HTTP 404 with the same shape).
- `fix.action`: `retry` | `add_sol` | `use_token_account` | `none`. `fix.params` keys: `slippage_bps`, `fresh_quote`, `refresh_route`, `compute_unit_limit`, `fresh_blockhash`, `sol`, `mint`.
- `handoff`: reserved for topics a person should decide; always `false` in the beta.
- Errors: `400` (bad signature), `429` (rate limit, honour `Retry-After`), `502`/`504` (RPC trouble) come back as `{"error": "..."}` in plain words.

## Rules for the agent
- Apply `fix` only when `fix.safe` is `true` and the action is within your mandate; never sign anything Unstuck returns — it returns parameters, not transactions.
- Never retry a transaction more than twice on the same fix.
- When `fix.safe` is `false` or `fix.action` is `none`, stop and ask a person, with `plain` and the chain context.
- Quote `plain` to users verbatim; keep `decoded` and `raw_message` for logs.

## Payment
Beta: calls are free; the x402 flow is the planned paid tier and is not enforced.

**Planned:** 0.10 USDC per `explain` call over x402 (USDC on Solana), no account; `errors` stays free. The API would answer `402` with a `PAYMENT-REQUIRED` header (`amount` `"100000"` = 0.10 USDC, asset `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`, network `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`); the client pays exactly that and resends with `X-PAYMENT`.