POST /explain

Synchronous transaction analysis over SSE - streams progress events, ends with the full result. For plain-fetch callers, use POST /explain/async and poll.

URL: https://mpp.oculr.xyz/explain

Auth: MPP/x402 metered session - requires tempo.session.manager().sse() from mppx, which signs voucher increments as the analysis accrues cost (metered pricing). A plain JSON request (no SSE) returns 402 with code: 'use_metered_sse'.

Request

Body

Headers

Response

200 OK - ExplanationResult

Delivered as the final { "type": "result", … } SSE event; the earlier events are progress. The example below is abbreviated - the field tables that follow list every field, and Analyze a transaction → Example result shows a response with all of them populated:

{
  "txHash": "0x…",
  "chain": "ethereum-mainnet",
  "chainName": "Ethereum",
  "status": "success",
  "summary": "Uniswap V3 swap: 1,000 USDC → 0.42 WETH via the 0.05% fee pool",
  "steps": ["Sender called exactInputSingle on Uniswap V3 Router", "..."],
  "risks": [],
  "protocol": "uniswap_v3",
  "txType": "swap",
  "confidence": "high",
  "usdValue": 1000.00,
  "addresses": [
    { "address": "0x…", "label": "Uniswap V3 Router", "role": "router" }
  ],
  "contracts": [
    { "address": "0x…", "name": "UniswapV3Pool", "description": "0.05% fee USDC/WETH pool" }
  ],
  "costs": {
    "llms":           0.33,
    "dataCollection": 0.03,
    "codeExecution":  0.01,
    "other":          0.00,
    "totalUsd":       0.37
  }
}

Response fields

Always present (partial results populate these with empty or placeholder values rather than omitting them)

Examples

TypeScript

import { tempo } from 'mppx/client'
 
const session = tempo.session.manager({ account, maxDeposit: '32' })
const stream = await session.sse('https://mpp.oculr.xyz/explain', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'Accept': 'text/event-stream' },
  body: JSON.stringify({
    txHash: '0x4e4b8ed4de38be29e3a7a15e2b14b5d8262e3c5b3f1e9d6a7c8b9e0f1a2d3c4e',
    model: 'claude-sonnet-4-6', // optional - cheaper than Opus
  }),
})
 
let result
for await (const payload of stream) {
  const msg = JSON.parse(payload)
  if (msg.type === 'result') result = msg
}

SSE streaming

Each agent step emits its own SSE message - preflight_start, preflight_done, preflight_status, iteration, agent_text (token-by-token reasoning), tool_call, tool_result, skill_call, tokens, complete, then either a final result (JSON) or report (HTML); fatal failures arrive as an error frame. The stream is what carries the metered payment: the session client signs voucher increments as cost accrues.

Prefer a plain fetch() and no stream? Use POST /explain/async - single-event polling, metered to the same total price.

Errors

402 handling

If the body carries code: 'use_metered_sse', you sent a plain JSON request - switch to Accept: text/event-stream with tempo.session.manager().sse(), or use POST /explain/async for plain fetch. Otherwise, a 402 with the session client active usually means your wallet ran out of USDC.e - top up at the USDC.e contract on Tempo (0x20C000000000000000000000b9537d11c60E8b50).

upstream_payment_unavailable handling

The server's outbound payment to one of its upstreams failed. Your payment is fine, so do not retry it as a payment failure. Surface to the user as something like "the transaction analysis service is temporarily unable to bill its upstreams - try again shortly." Cap retries at 2.

One condition, three shapes - and on the hosted API the HTTP status is the wrong thing to branch on. Which shape you get depends on the rail:

A client that branches only on res.status === 502 therefore never fires against the hosted API. The async pattern:

const { jobId } = await fetch('https://mpp.oculr.xyz/explain/async', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ txHash }),
}).then(r => r.json())
 
while (true) {
  await new Promise(r => setTimeout(r, 5000))
  // 200 even when the analysis failed: the status describes the poll, not the job.
  const job = await fetch(`https://mpp.oculr.xyz/result/${jobId}`).then(r => r.json())
  if (job.status === 'complete') return job.result
  if (job.status === 'error') {
    if (job.errorCode === 'upstream_payment_unavailable') {
      throw new Error('oculr is temporarily unable to bill its upstreams - try again shortly')
    }
    throw new Error(job.error)
  }
}

Note: most upstream issues don't surface as 500 or 502. oculr returns 200 OK with confidence: 'low' and a summary that starts with "Partial result" whenever it can produce a usable partial result. See Core concepts → Partial results.

Related

• POST /explain/async - non-blocking variant
• Analyze a transaction - worked example with the result schema explained
• Core concepts → Partial results