SandwichCheck API · v0.2.0

API docs

Read-only API for transaction-level MEV signals on Ethereum Mainnet and Sepolia. Responses are JSON. The machine-readable spec is at /openapi.json.

GET/api/analyze

Analyze a Mainnet or Sepolia transaction for supported MEV patterns. Returns a forensic classification and the evidence behind it.

Query parameters
q required
Transaction hash (0x + 64 hex) or wallet address (0x + 40 hex).
network
mainnet (default) or sepolia.
Request
curl "https://sandwichcheck.com/api/analyze?network=mainnet&q=0xb4e7736a7cbe95d29940a20710fa57e5fa6f9a878427547e355fd1d5a9de97f2"
Response · 200
{
  "network": "mainnet",
  "query_type": "transaction",
  "transaction_hash": "0xb4e7736a7cbe95d29940a20710fa57e5fa6f9a878427547e355fd1d5a9de97f2",
  "wallet": "0xf204f3acb05c405c0010f2a2ecfa9fe61783f1d1",
  "verdict": "mev_activity",
  "summary": "A possible same-pool backrun follows this swap; no linked frontrun was found.",
  "block_number": 26078521,
  "transaction_position": 48,
  "block_transaction_count": 259,
  "frontrun_tx_hash": null,
  "backrun_tx_hash": null,
  "evidence": ["Transaction is 48 of 259 in the mined block."],
  "signals": [{
    "kind": "backrun_candidate",
    "label": "Possible backrun",
    "confidence": "low",
    "role": "preceding_transaction",
    "summary": "An opposite-direction swap from 0xbc73…a21c follows this swap in the same pool.",
    "related_transactions": ["0xd6408dd05f5ab888d8e151558e8221cfab64b9e8102e3bb0e7d72329a316d2ca"]
  }],
  "coverage": ["sandwich", "copied_frontrun", "backrun_candidate", "liquidation", "multi_pool_arbitrage_candidate"]
}
Verdicts
mev_detected
High confidence pattern, such as a linked sandwich.
mev_activity
Candidate: one or more supported signals, but a link is missing or indirect.
no_mev_detected
No pattern found within current coverage.
pending · reverted · not_found · unsupported
The transaction cannot be graded.
Errors
400
Invalid transaction hash, address, or network.
502
Ethereum RPC request failed.
503
Selected network RPC is not configured.

GET/api/network

Configured network status. Reports whether each RPC endpoint is present, never the secret itself.

[
  { "network": "mainnet", "chain_id": 1, "rpc_configured": true },
  { "network": "sepolia", "chain_id": 11155111, "rpc_configured": true }
]

GET/health

Health check. Returns 200 when the backend is healthy.

{ "status": "ok", "service": "mev-protection-backend" }

POST/api/runs

Queue a local control-test run. Returns the queued run.

GET/api/runs/latest

Get the latest run, or null when none exists.

GET/api/opportunities

List the newest 50 recorded sandwich opportunities.

POST/api/opportunities

Record a sandwich-worthy transaction. Returns the recorded opportunity, or 400 when required fields are missing.

Body · application/json
tx_hash required
Transaction hash, for example 0xabc123.
chain_id required
Integer chain ID, for example 1.
estimated_profit_wei required
Decimal integer string.
estimated_victim_loss_wei required
Decimal integer string.
detection_source required
For example mined-receipt-window.
minimum_profit_wei required
Threshold used by the detector, as a decimal integer string.