{
  "markdown": "# magpie-x402\n\n## Solana lending protocol — liquidity without selling your bag.\n\nBorrow SOL against your memecoins, tokenized stocks, and RWAs — and set take-profits and stops on that same collateral. Liquidity now, upside intact: collateral that can still sell itself.\n\n**x402 payment-required API endpoints for the [Magpie Capital](https://magpie.capital) protocol.** AI agents and other Solana protocols can pay-per-call for credit scores, token risk assessments, and protocol analytics — no API keys, no signups, just a Solana payment. Agents borrow programmatically: pay per call, get back an *unsigned* Solana transaction, sign and submit it yourself (the service holds zero keys).\n\nTake-profit, stop-loss, ladders, trailing stops — they fire on-chain into your loan's vault, the loan stays open, and proceeds reach your wallet only when you repay. Auto-sell exits are V4 in-vault orders on supported collateral (memecoins + tokenized stocks/RWAs); they are auto-sell orders that fire on-chain through a slippage stack, not guaranteed fills.\n\n```\n                        AI agent\n                            │\n                            │  GET /api/v1/credit-score?wallet=…\n                            ▼\n                ┌────────────────────┐\n                │ 402 Payment        │\n                │ Required           │  ← scheme, recipient, amount, nonce\n                └─────────┬──────────┘\n                          │\n                          │  Solana tx\n                          ▼            (transfer to MAGPIE_PAY_TO\n              ┌────────────────────┐    + memo `magpie-x402:<nonce>`)\n              │ on-chain ↪ Solana  │\n              └─────────┬──────────┘\n                        │\n                        │  retry GET with header X-Payment: <signature>\n                        ▼\n              ┌────────────────────┐\n              │  Service verifies  │  ← amount, recipient, mint, memo nonce,\n              │  payment on-chain  │    nonce not previously consumed\n              └─────────┬──────────┘\n                        │\n                        ▼\n                 { score, tier, … }\n```\n\n## What this is (and isn't)\n\n- ✅ **An open standard implementation.** [x402](https://x402.dev) is HTTP 402 Payment Required, designed for AI-agent-payable APIs.\n- ✅ **A revenue path for protocol data.** Magpie's credit oracle, token risk scores, and analytics are useful to OTHER protocols and agents — this is how they pay for that access.\n- ✅ **Public-data-only.** Every response field corresponds to data already verifiable on-chain via [solscan.io](https://solscan.io) or in the [magpie-bot](https://github.com/magpiecapital/magpie-bot) source.\n- ❌ **Not custodial.** This service holds no keys, signs no transactions, cannot move any user funds. Even a full RCE on this host can't drain a user — see [SECURITY.md](./SECURITY.md).\n\n## Endpoints\n\n| Method | Path | Price | Description |\n|--------|------|-------|-------------|\n| GET | `/` | Free | Service info + endpoint catalog |\n| GET | `/health` | Free | Liveness check |\n| GET | `/.well-known/x402.json` | Free | Machine-readable endpoint catalog (auto-discovery) |\n| GET | `/openapi.json` | Free | OpenAPI 3.1 spec (for agent frameworks) |\n| GET | `/api/v1/pool` | Free | Live on-chain LendingPool state — totalDeposits, totalBorrowed, lifetime counters. 15s cache. |\n| GET | `/api/v1/pools` | Free | All three strategy pools (V1 memecoin / V3 RWA / V4 in-vault) in one call, with a `partial` map if any version is unreachable. 15s cache. |\n| GET | `/api/v1/loan/:loanId?borrower=<pubkey>` | Free | Loans matching a u64 ID across V1/V3/V4. Returns a list (a borrower can hold the same numeric ID in more than one program) — each tagged with `program_version`. 10s cache. |\n| GET | `/api/v1/loan/by-pda/:loanPda` | Free | Single loan by its PDA — unambiguous, routed to V1/V3/V4 from the on-chain owner. Returns `program_version`, V4 in-vault exit state, and `exits_supported`. 10s cache. |\n| GET | `/api/v1/wallet/:wallet/loans?status=...` | Free | All loans owned by a wallet across V1/V3/V4 via `getProgramAccounts` + memcmp filter, each tagged with `program_version` (with a `by_version` count). Optional status filter. 8s cache. |\n| GET | `/api/v1/collateral/eligible` | Free | Catalog of every token currently approved as Magpie collateral. First-touch for new agent integrations. 1h cache. |\n| GET | `/api/v1/markets/liquidatable` | Free | Active loans at or past their on-chain due timestamp across V1/V3 — the canonical liquidation-bot data feed, each tagged with `program_version`. Sorted most-past-due-first. Optional `?within_seconds=` for pre-positioning, `?include_v4=true` to include in-vault V4 loans. 8s cache. |\n| GET | `/api/v1/agent/activity` | Free | Anonymized recent borrow/repay/liquidate events. First-touch \"is this protocol alive?\" feed for arriving agents. 15s cache. |\n| GET | `/api/v1/agent/protocol-pulse` | Free | 24h aggregates: active loans, active borrowers, borrow volume, liquidations. 30s cache. |\n| GET | `/api/v1/agent/leaderboard` | Free | Top wallets by Magpie credit score, anonymized. 60s cache. |\n| GET | `/api/v1/agent/lp-state?wallet=<pubkey>` | Free | Depositor position + pool context (shares, deposited, current value, yield, share-of-pool). 10s cache. |\n| GET | `/api/v1/agent/self-limit-close/list?wallet=<pubkey>` | Free | A wallet's armed in-vault exit orders (TP/SL) on its V4 loans. |\n| GET | `/api/v1/credit-score?wallet=<pubkey>` | 0.001 SOL | Magpie credit score (300–850) + tier benefits |\n| POST | `/api/v1/agent/build-borrow` | 0.005 SOL | Build an unsigned borrow tx. Pass `has_exit_arming: true` to route to the V4 in-vault program (so exit orders can be armed on the loan); otherwise routes to V1 (memecoin) — and, once it launches, V3 (RWA). |\n| POST | `/api/v1/agent/build-deposit` | 0.002 SOL | Build an unsigned LP-deposit tx (SOL → pool). Caller signs and submits. |\n| POST | `/api/v1/agent/build-withdraw` | 0.002 SOL | Build an unsigned LP-withdraw tx (shares → SOL). Server validates against the on-chain position and refuses unsafe chunk sizes. |\n| POST | `/api/v1/agent/self-limit-close/arm` | 0.001 SOL | Arm an in-vault take-profit / stop-loss on your OWN V4 loan. Body is an Ed25519 signed envelope; pays AND signs with the same keypair, so payer == signer. Bot enforces ownership + V4-only. |\n| POST | `/api/v1/agent/self-limit-close/modify` | Free | Modify an armed exit order (signed envelope). |\n| POST | `/api/v1/agent/self-limit-close/cancel` | Free | Cancel an armed exit order (signed envelope). |\n\nAll free endpoints query the on-chain Magpie program directly and have proper `Cache-Control` headers so CDN edges serve repeat reads without round-tripping.\n\nLoan and pool reads are **multi-version**: every loan/pool is resolved across the V1 (memecoin), V3 (RWA — on the V3 launch), and V4 (in-vault auto-sell) programs and tagged with its `program_version`. These reads fail soft — if one version is unreachable, the rest still return and the affected version is reported in a `partial` map rather than erroring the whole call. The `/api/v1/agent/self-limit-close/*` surface lets a borrower-agent arm, modify, cancel, and list **self-owned** in-vault exit orders (take-profit / stop-loss) on its own V4 loans, authenticated by an Ed25519 signed envelope where the x402 payer is also the envelope signer.\n\n> 🚀 **Building your first Magpie agent?** Read [`QUICKSTART.md`](./QUICKSTART.md) — zero to a working autonomous borrow agent on Solana in 10 minutes, using the typed SDK.\n>\n> 📦 **TypeScript SDK** (`@magpieloans/magpie-agent`): every action as a one-liner. Borrow, lend, liquidate, post conditional intents — no HTTP plumbing. See [`sdk/README.md`](./sdk/README.md).\n>\n> 🧩 **MCP server** for Claude Desktop / Cursor / Windsurf / ChatGPT desktop: one config block, 26 tools. See [`mcp/README.md`](./mcp/README.md).\n>\n> 🎯 **Limit-close agent quickstart** — full end-to-end walkthrough for agents that arm, monitor, and steer limit-close (TP/SL) orders on borrowers' loans. Authorization flow, every endpoint, sample code, error reference, best practices. See [`docs/AGENT_QUICKSTART_LIMIT_CLOSE.md`](./docs/AGENT_QUICKSTART_LIMIT_CLOSE.md).\n>\n> 👉 **Just want code examples?** [`/examples/`](./examples/) — 13 turn-key TypeScript agents (credit fetch, liquidation keeper, full borrow loop, conditional intent, yield agent, webhook receiver, collateral screener, equity-leverage preview, more) that talk to the live production endpoint. Each is a single file, runs with `npx tsx`.\n>\n> 🧩 **Using Claude Desktop, Cursor, Windsurf, or ChatGPT desktop?** [`/mcp/`](./mcp/) ships a one-config-block MCP server that exposes the full API as native tools in your agent host. Free reads work without any keypair; paid endpoints sign x402 payments locally with a configured Solana wallet.\n\nMore paid endpoints in progress (token risk score, batch credit lookups, webhook subscriptions, MCP server, LP-side build-deposit / build-withdraw) — see [MARKETING.md](./MARKETING.md) for the agent-distribution roadmap or open an issue if you want one prioritized.\n\n## How to call a paid endpoint\n\n### Step 1 — get the challenge\n\n```bash\ncurl -i https://x402.magpie.capital/api/v1/credit-score?wallet=9UuLsJ3jf8ViBNeRcwXD53re5G3ypgfKK3s2EiMMpump\n```\n\nResponse:\n\n```http\nHTTP/2 402\nX-Payment-Required-Scheme: x402/solana/v1\nX-Payment-Required-Amount: 1000000\nX-Payment-Required-Recipient: <MAGPIE_PAY_TO pubkey>\nX-Payment-Required-Nonce: a1b2c3...\nX-Payment-Required-Memo: magpie-x402:a1b2c3...\n\n{\n  \"error\": \"payment_required\",\n  \"scheme\": \"x402/solana/v1\",\n  \"payTo\": \"...\",\n  \"amountLamports\": \"1000000\",\n  \"nonce\": \"a1b2c3...\",\n  \"memo\": \"magpie-x402:a1b2c3...\",\n  \"instructions\": \"Send 1000000 lamports of SOL to ... with memo 'magpie-x402:...', then retry with header X-PAYMENT: <tx_signature>\"\n}\n```\n\n### Step 2 — pay on Solana\n\nSend a `SystemProgram::transfer` (or SPL Token transfer) for the exact amount to the recipient pubkey, with the **memo** instruction containing the challenge string. Confirm.\n\n### Step 3 — retry with the signature\n\n```bash\ncurl -i \\\n  -H \"X-Payment: <your_tx_signature>\" \\\n  https://x402.magpie.capital/api/v1/credit-score?wallet=9UuLsJ3jf8ViBNeRcwXD53re5G3ypgfKK3s2EiMMpump\n```\n\nResponse:\n\n```json\n{\n  \"wallet\": \"9UuLsJ...\",\n  \"score\": 712,\n  \"tier\": \"gold\",\n  \"range\": { \"min\": 300, \"max\": 850 },\n  \"benefits\": { \"maxLtvPercent\": 35, \"minFeeRate\": 0.0125, \"maxDurationDays\": 14 },\n  \"source\": \"magpie-credit-oracle\"\n}\n```\n\n## Local development\n\n```bash\ngit clone git@github.com:magpiecapital/magpie-x402.git\ncd magpie-x402\ncp .env.example .env       # fill in MAGPIE_PAY_TO + MAGPIE_LENDER_PUBKEY\nnpm install\nnpm run dev                 # http://localhost:8402\n```\n\n## Deploy to Vercel (1-click)\n\nThe repo is structured for Vercel serverless out of the box:\n- `api/index.ts` — Vercel-native entry, handles every request via `hono/vercel` adapter\n- `vercel.json` — routes all paths to `/api`\n- `src/app.ts` — the shared Hono app (also used by local dev)\n- `src/index.ts` — local-dev Node server (NOT used by Vercel)\n\n### Step-by-step\n\n1. **In the Vercel dashboard, click \"Add New\" → \"Project\"**\n2. **Import `magpiecapital/magpie-x402` from GitHub**\n3. **Framework Preset:** \"Other\" (Vercel auto-detects via vercel.json)\n4. **Set Environment Variables** (Production + Preview + Development):\n   - `MAGPIE_PAY_TO` — your Solana treasury pubkey\n   - `MAGPIE_LENDER_PUBKEY` — the Magpie lender authority\n   - `SOLANA_RPC_URL` — use a paid Helius/Triton/QuickNode URL for speed (public RPC will rate-limit you)\n   - `CORS_ORIGINS` — comma-separated allowlist (use `*` only during testing)\n   - `RATE_LIMIT_PER_MIN` and `RATE_LIMIT_PER_HOUR` — tune per traffic\n5. **Click Deploy.** First build runs `npm install && npm run build` (or just `npm install` since Vercel handles TS) — ~1 minute.\n6. **Test:** `curl https://<your-deployment>.vercel.app/api/v1/pool`\n\n### Custom domain\n\nAfter the first deploy, in **Settings → Domains** attach `x402.magpie.capital` (or any subdomain you control). Vercel handles the TLS cert automatically.\n\n### Why Node runtime, not Edge\n\n`@solana/web3.js` depends on Buffer + Node crypto primitives that don't ship in Vercel's Edge runtime. Once `@solana/kit` (web3.js v2) stabilizes for Edge, switching gets us another latency win — but Node serverless is plenty fast for v0 (cold start ~150–250ms, warm <10ms server-side).\n\n### Multi-instance considerations (caveat for high-scale deploys)\n\nThe in-memory nonce store (in `src/middleware/x402.ts`) and rate-limit buckets are per-instance. At low traffic, Vercel runs a single warm instance and this works fine. At high concurrency, Vercel scales horizontally — a payment challenge issued by instance A might fail validation on instance B because B hasn't seen the nonce.\n\nWhen that becomes a problem (it isn't for v0 — but if you push >20 req/s sustained, plan for it):\n- **Option 1:** HMAC-sign the nonces with a server secret. Stateless, infinitely scalable, no external dependency.\n- **Option 2:** Wire Vercel KV (Upstash Redis) for shared state. Drop-in via `@vercel/kv`.\n\nBoth paths sketched in `SECURITY.md` under \"production hardening\".\n\n## Security\n\nSee [SECURITY.md](./SECURITY.md) for the full posture. Highlights:\n\n- **No keys ever stored or signed.** This service verifies incoming payments only.\n- **No secrets in source.** All config via env vars; `.env` is gitignored; `.gitignore` excludes any file matching `*keypair*.json`, `*.pem`, `*.key`, etc.\n- **Replay-resistant.** Single-use nonces bound to payment memos.\n- **On-chain re-derivation.** Amount, recipient, and mint are always re-read from the on-chain transaction — never trusted from the client.\n- **Rate-limited from day one** — per-IP minute + hour buckets on every endpoint.\n- **Generic error responses** — verification logic isn't leaked through error messages.\n\nTo report a vulnerability: open a GitHub issue tagged `security`, or contact us via https://magpie.capital/security.\n\n## Related repos\n\n- [magpiecapital/magpie-bot](https://github.com/magpiecapital/magpie-bot) — the Telegram wallet bot + Anchor programs\n- [magpiecapital/magpie-site](https://github.com/magpiecapital/magpie-site) — the web app\n- [Magpie Capital](https://magpie.capital) — protocol overview + live stats\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n",
  "bytes": 14369,
  "sha": "2fb812114180d14e343c2bcc59085b1f2abd677b544e88804019bd399d4df154",
  "repo_slug": "magpiecapital/magpie-x402",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_magpiecapital_magpie_mcp_9434ee52/readme"
}