# Transaction lifecycle API

Watch one covered Solana submission move to its exact landed block, execution result, and final commitment through one cursor-based request loop.

You are helping a user call this API. This document is the complete
contract: every endpoint, its parameters and request body, the auth, and
the MCP surface. Generate runnable `curl`/TypeScript/Python on demand
using the values below; replace the placeholder key with the user's real
`k256_live_` key.

- Base URL: `https://api.k256.xyz`
- Data plane: `https://api.k256.xyz/v1/stls`
- OpenAPI: `https://api.k256.xyz/stls/api/spec.json`
- MCP (for agents): `https://api.k256.xyz/stls/mcp` (server name `k256-gateway`) — the same operations as 1:1 tools.
- MCP writes need one extra argument: every tool whose `Action` below is `write` requires `confirm_mcp_write: true`. Reads take no such argument.
- Auth: every request needs `Authorization: Bearer <YOUR_API_KEY>`. Never put the key in a URL query string.

STLS exposes one read-only operation: GET /v1/stls/{cluster}/transactions/{signature}. Use only mainnet, devnet, or testnet. Add sent_at_slot when the submission slot is known; an unretained signature without it is unknown, not pending. Keep at most one held request outstanding per signature. Pass the prior cursor with wait=25, reconnect after nonterminal responses, and stop at finalized. A reverted response means the prior candidate block was proved to have lost its fork; it is not a landed outcome.

## Endpoints

### `GET /v1/stls/{cluster}/transactions/{signature}` — Get a Solana transaction lifecycle
- Action: `read` · MCP tool: `stls.get_transaction_lifecycle`
- Returns the exact on-chain lifecycle for one signature — recent or older, including finalized transactions past the live window. A signature that cannot be resolved is unknown, never guessed pending; pass sent_at_slot to get pending for a not-yet-landed signature. To watch for a change, send the returned cursor with wait=25 and keep at most one request outstanding. Stop after finalized.
- Path param `cluster` (string, required) — mainnet, devnet, or testnet
- Path param `signature` (string, required) — Canonical base58 64-byte transaction signature
- Query param `cursor` (string) — Cursor returned by the previous response
- Query param `wait` (string) — Whole seconds from 0 through 25
- Query param `sent_at_slot` (string) — Exact base-10 unsigned 64-bit submission slot
- Response (JSON):
  - `cluster` — "mainnet" | "devnet" | "testnet"
  - `signature` — string
  - `status` — "unknown" | "pending" | "processed" | "confirmed" | "finalized" | "reverted"
  - `slot` — integer | null
  - `succeeded` — boolean | null
  - `block` — object | null
    - `hash` — string
    - `height` — integer | null
    - `time` — integer | null
    - `leader` — string | null
  - `cursor` — string
  - `changed` — boolean