# Sol-Incinerator Burn Instruction API v2

Machine-oriented integration notes.

Base URL: `https://v2.api.sol-incinerator.com`

## Canonical Discovery

- LLM index: `https://v2.api.sol-incinerator.com/llms.txt`
- Expanded text: `https://v2.api.sol-incinerator.com/llms-full.txt`
- OpenAPI: `https://v2.api.sol-incinerator.com/openapi.json`
- API catalog: `https://v2.api.sol-incinerator.com/.well-known/api-catalog`
- Human docs: `https://v2.api.sol-incinerator.com/DOCS.md`
- Hosted MCP: `https://v2.api.sol-incinerator.com/mcp`

## Two-Lane Access Model

### Lane 1: Autonomous agents (no user input)

- Generate an API key via `POST /api-keys/generate`.
- Use the API key on core HTTP endpoints.
- Recommended when an LLM/agent is running unattended.

### Lane 2: Human-driven IDE agents (Codex/Claude)

- Use hosted MCP endpoint: `https://v2.api.sol-incinerator.com/mcp`.
- Authenticate MCP with browser OAuth (or bearer API key fallback).

## MCP Endpoint

- Transport: Streamable HTTP
- URL: `https://v2.api.sol-incinerator.com/mcp`
- OAuth resource metadata: `https://v2.api.sol-incinerator.com/.well-known/oauth-protected-resource`
- OAuth authorization server metadata: `https://v2.api.sol-incinerator.com/.well-known/oauth-authorization-server`
- Tools:
  - `signing_requirements`
  - `burn`, `burn_preview`, `burn_instructions`, `close`, `close_preview`, `close_instructions`, `close_wallet`, `close_wallet_preview`, `batch_close_all`, `batch_close_all_preview`, `batch_close_all_summary`, `batch_close_all_instructions`, `cleanup_all`, `cleanup_all_summary`, `pump_summary`, `pump_close_all`, `pump_close_all_instructions`, `send_transaction`, `send_transaction_batch`, `get_transaction_status`
  - `get_status`, `get_openapi`, `get_api_catalog`, `get_llms_index`, `get_llms_markdown`, `get_llms_full`, `get_docs_markdown`
- Auth options:
  - Browser OAuth flow via MCP client authenticate button
  - `Authorization: Bearer <api_key>`

## Core Endpoint Group (API-key required)

- `POST /burn`
- `POST /burn/preview`
- `POST /burn-instructions`
- `POST /close`
- `POST /close/preview`
- `POST /close-instructions`
- `POST /batch/close-all`
- `POST /batch/close-all/preview`
- `POST /batch/close-all/summary`
- `POST /batch/close-all-instructions`
- `POST /cleanup/all`
- `POST /cleanup/all/summary`
- `POST /pump/summary`
- `POST /pump/close-all`
- `POST /pump/close-all-instructions`
- `POST /transactions/send`
- `POST /transactions/send-batch`
- `POST /transactions/status`

### Transaction Relay Flow (non-custodial)

1. Build transaction(s) on `/burn`, `/close`, `/batch/close-all`, or `/cleanup/all`.
2. Sign locally with the wallet keypair/private key.
3. Send via `/transactions/send` or `/transactions/send-batch`.
4. Track with `/transactions/status` (or set `waitForConfirmation` on send routes).

## Portal/Auth Endpoint Group

- `POST /portal/auth/challenge`
- `POST /portal/auth/verify`
- `POST /portal/auth/logout`
- `GET /portal/me`
- `GET /portal/api-keys`
- `POST /portal/api-keys`
- `PATCH /portal/api-keys/:keyId`
- `POST /portal/api-keys/:keyId/rotate`
- `GET /portal/usage/summary`
- `GET /portal/usage/timeseries`
- `GET /portal/usage/endpoints`
- `GET /portal/usage/errors`
- `GET /portal/usage/requests`

## Admin Endpoint Group

- `GET /admin/usage/summary`
- `GET /admin/usage/users`
- `GET /admin/usage/api-keys`
- `GET /admin/usage/requests`
- `GET /admin/usage/users/:userId/summary`
- `GET /admin/usage/users/:userId/endpoints`
- `POST /admin/users/grant-admin`
- `GET /admin/users/:userId/api-keys`
- `POST /admin/users/:userId/api-keys/:keyId/suspend`
- `POST /admin/users/:userId/api-keys/:keyId/activate`

## Partner and Referral Inputs

Core operation bodies accept:
- `partnerFeeAccount` (pubkey)
- `partnerFeeBps` (integer `0..9800`)
- `referralCode` (string `2-20` lowercase alphanumeric)

Validation:
- both partner fields must be supplied together or both omitted.
- `referralCode` cannot be combined with partner fee fields.

## MPL Core Frozen Semantics

- For MPL Core NFTs, `assetInfo.frozen` is not limited to direct freeze delegates.
- The API also marks the asset as frozen when a `permanentBurnDelegate` exists that the owner cannot use.
- Collection-level permanent freeze also marks the asset as frozen unless the owner has permanent burn authority.

## Rate Limits

Per route+identity per 60 seconds:
- standard routes: 240 RPM
- heavy close-all routes: 60 RPM

## Error Shape

```json
{ "error": "..." }
```