DEVELOPER GUIDE
Build with evidence, not assumptions.
Start with the public demo. Add an API key or supported payment rail when you need protected responses. All reference content below is available without JavaScript.
1. Try a public request
The allowlisted Base USDC example needs no API key. This command makes a live request; the documentation itself does not.
curl --max-time 20 \
"https://api.m2msentinel.com/v1/demo/audit/0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"Look for audit, evidenceGrade, provenance and limitations. Other addresses can receive a limited PREVIEW rather than a full audit. A live dependency failure is not an empty or successful observation.
2. Choose access deliberately
Send API keys only through x-api-key or Authorization: Bearer. URL credentials are rejected. Never embed a production key in public client code or share it in a link.
curl --max-time 20 \
"https://api.m2msentinel.com/v1/audit/0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" \
-H "x-api-key: $M2M_SENTINEL_API_KEY"For routes supporting x402 v2, an unauthenticated request returns HTTP 402 with a PAYMENT-REQUIRED challenge when the payment rail is available. Review and settle the challenge, then retry with PAYMENT-SIGNATURE. Not every route supports x402: key self-service and transaction preflight have different requirements, documented below.
RapidAPI subscriptions use gateway keys and marketplace billing, not native sk_live_... keys. Quotas and authorization still apply. A crawler receives the same access boundary as any other client.
Handle errors without guessing
401: invalid or disallowed credentials. Do not move credentials into a URL.402: payment or plan action required; inspect the returned challenge and error.429: a quota or rate limit was reached. HonorRetry-Afterwhen present.503: required evidence, storage or settlement is unavailable. Do not substitute a fabricated successful result.
3. Endpoint reference
Generated at build time from OpenAPI 3.1, including public, protected, key-management and MCP operations. Expand any route for its conditions, parameters and documented responses. Fragment links are shareable.
GET/v1/statusInstantaneous dependency health
Access: No route-level credential. Additional wallet, session or operator conditions may apply as described below.
Reports the live state of persistence, Base RPC trust, verdict quality and payment settlement. Returns 503 when both persistence and RPC are unreachable. Historical availability is published only for windows with sufficient recorded health samples. The legacy core series measures persistence plus Base RPC; gateway, paid x402 route and RapidAPI marketplace series are reported independently.
Documented responses
200— Health snapshot503— All core dependencies are unreachable
GET/v1/operator/rapidapi-proxy-digestDerive the RapidAPI gateway proxy-secret digest during a one-time bootstrap
Access: Operator-only RapidAPI bootstrap token
Disabled unless RAPIDAPI_BOOTSTRAP_TOKEN contains at least 32 characters. Call this route through RapidAPI and authenticate with x-m2m-rapidapi-bootstrap. The request must include a non-empty RapidAPI-injected x-rapidapi-proxy-secret plus at least one non-empty RapidAPI context header (x-rapidapi-user, x-rapidapi-subscription, x-rapidapi-host, or x-rapidapi-key). The response contains only the lowercase SHA-256 digest; the raw proxy secret is never reflected or persisted. After copying the digest into RAPIDAPI_PROXY_SECRET_SHA256, remove RAPIDAPI_BOOTSTRAP_TOKEN and any raw RAPIDAPI_PROXY_SECRET value, which makes this route return 404.
Parameters
x-rapidapi-proxy-secret(header, required) — The non-empty private proxy secret injected by RapidAPI. It is hashed in memory and is never returned.x-rapidapi-user(header, optional) — RapidAPI forwarding context. At least one of this header, x-rapidapi-subscription, x-rapidapi-host, or x-rapidapi-key must be non-empty.x-rapidapi-subscription(header, optional)x-rapidapi-host(header, optional)x-rapidapi-key(header, optional)
Documented responses
200— The proxy secret digest. No raw secret or identifying metadata is included.400— Malformed input401— Missing or invalid credential, or a credential was supplied in the query string404— Bootstrap is disabled because no strong RAPIDAPI_BOOTSTRAP_TOKEN is configured.
GET/v1/statsPublic telemetry metadata or operator-authorized aggregate detail
Access: No route-level credential. Additional wallet, session or operator conditions may apply as described below.
Without operator authorization this returns no exact adoption, funnel, utilization, attribution, or revenue counters. A Bearer OPERATOR_STATS_TOKEN returns identifier-free global daily counters. No IP address, wallet, API key, contract address, path parameter, user agent, referrer, or per-user identifier is collected.
Parameters
days(query, optional)bucket(query, optional) — Operator-only. Selects the analytics bucket to read. 'test' returns the segregated bucket that authenticated live probes write to, so operator traffic can be reconciled separately from customer traffic. Supplying this parameter without operator authorization returns 401.
Documented responses
200— Redacted public metadata, or detailed counters when operator-authorized429— A plan burst limit or bounded public/intent retry limit was exceeded
POST/v1/eventsRecord an allowlisted first-party aggregate event
Access: No route-level credential. Additional wallet, session or operator conditions may apply as described below.
Accepts only pageViewed and ctaClicked plus fixed enum dimensions. Commercial outcomes are recorded authoritatively by server routes. Unknown fields, free text and identifiers are refused.
Request body (required): application/json. See the OpenAPI contract for the complete schema.
Documented responses
202— Valid aggregate event accepted400— Malformed input429— A plan burst limit or bounded public/intent retry limit was exceeded
GET/v1/demo/audit/{address}Run live capability analysis or tiered preview for any Base contract
Access: No route-level credential. Additional wallet, session or operator conditions may apply as described below.
Uses live Base RPC, proxy resolution, and bytecode capability analysis. For published allowlisted samples, returns full audit evidence. For arbitrary addresses, returns a tiered preview with high-level capability indicators and an upgrade prompt.
Parameters
address(path, required) — Base smart contract address (20-byte hexadecimal, checksummed or lowercase)
Documented responses
200— Live sample analysis400— Malformed input503— A required dependency is unavailable; the request failed closed
GET/v1/plansAuthoritative plan and pricing catalogue
Access: No route-level credential. Additional wallet, session or operator conditions may apply as described below.
The single source of truth for pricing. The website renders this endpoint; if any page disagrees with it, this endpoint governs.
Documented responses
200— Plan catalogue
POST/v1/subscribe/free/challengeRequest a wallet challenge for a free key
Access: No route-level credential. Additional wallet, session or operator conditions may apply as described below.
Request a wallet challenge for a free key
Request body (required): application/json. See the OpenAPI contract for the complete schema.
Documented responses
200— Challenge issued400— Malformed input429— A plan burst limit or bounded public/intent retry limit was exceeded503— A required dependency is unavailable; the request failed closed
POST/v1/subscribe/free/claimExchange a signed challenge for a free key
Access: No route-level credential. Additional wallet, session or operator conditions may apply as described below.
Allocated once per wallet. The raw key is returned exactly once and is never recoverable afterwards.
Request body (required): application/json. See the OpenAPI contract for the complete schema.
Documented responses
200— Key issued400— Malformed input401— Missing or invalid credential, or a credential was supplied in the query string409— A free key already exists for this wallet429— A plan burst limit or bounded public/intent retry limit was exceeded503— A required dependency is unavailable; the request failed closed
POST/v1/subscribe/intentsCreate a signable purchase intent with a frozen quote
Access: No route-level credential. Additional wallet, session or operator conditions may apply as described below.
The exact USDC amount (and, when a live ETH quote exists, the exact wei amount), duration and optional same-key renewal target are frozen into the message you sign. The intent is valid for 15 minutes. Renewals require the active same-tier paid key in x-api-key; changing tiers requires a new key.
Request body (required): application/json. See the OpenAPI contract for the complete schema.
Documented responses
200— Intent created400— Malformed input401— Missing or invalid credential, or a credential was supplied in the query string429— A plan burst limit or bounded public/intent retry limit was exceeded503— A required dependency is unavailable; the request failed closed
POST/v1/subscribe/cryptoClaim a subscription key after on-chain payment
Access: No route-level credential. Additional wallet, session or operator conditions may apply as described below.
Requires 3 block confirmations and a credentialed RPC. The signer of the intent, the transaction sender and the payment sender must be the same wallet. A transaction hash can be redeemed exactly once.
Request body (required): application/json. See the OpenAPI contract for the complete schema.
Documented responses
200— Payment verified and key provisioned400— Intent, amount, sender or finality check failed429— A plan burst limit or bounded public/intent retry limit was exceeded503— A required dependency is unavailable; the request failed closed
GET/v1/audit/{address}Static bytecode capability and proxy observations
Access: API key in x-api-key OR API key in Authorization: Bearer OR Settled x402 payment
Reports selected bytecode patterns and common proxy structures. notASafetyGuarantee is always true; absence of a pattern is not evidence of safety.
Parameters
address(path, required) — Base smart contract address (20-byte hexadecimal, checksummed or lowercase)
Documented responses
200— Capability report.capabilityRatingisUNVERIFIEDandcapabilityScoreis null when RPC trust is below evidence grade.400— Malformed input401— Missing or invalid credential, or a credential was supplied in the query string402— No credential supplied for a payable route, or the issuance-anchored 31-day credit allowance is exhausted405— Verb not supported. HEAD is refused on protected routes because it would execute a metered handler while suppressing the body.429— A plan burst limit or bounded public/intent retry limit was exceeded503— A required dependency is unavailable; the request failed closed
POST/v1/transaction/preflightResolve the executing target for one Base transaction
Access: API key in x-api-key OR API key in Authorization: Bearer OR RapidAPI gateway key
API-key/RapidAPI metered transaction-specific evidence. Accepts one strictly validated Base mainnet transaction, pins one observation block before state-bearing reads, identifies the supplied four-byte selector and resolved implementation or Diamond facet, returns bytecode hashes, capability evidence and an eth_call observation when possible. Incomplete or unsupported paths stay explicit. The caller owns policy before signing. This route is not x402-payable and has no x402 price; an unauthenticated request receives the normal protected-route 401 response.
Request body (required): application/json. See the OpenAPI contract for the complete schema.
Documented responses
200— Verified or explicit bounded unverified transaction evidence. No safety, maliciousness, reachability, or exploitability conclusion is returned.400— The strict transaction preflight body failed validation before RPC, persistence, or quota work.401— Missing or invalid credential, or a credential was supplied in the query string402— The authenticated key has no remaining decision credit. This route does not offer an x402 challenge or price.405— Verb not supported. HEAD is refused on protected routes because it would execute a metered handler while suppressing the body.429— A plan burst limit or bounded public/intent retry limit was exceeded503— A trusted pinned Base observation or required surface read was unavailable. No decision credit was consumed.
GET/v1/security/score/{address}Legacy URL for the static capability coverage index
Access: API key in x-api-key OR API key in Authorization: Bearer OR Settled x402 payment
Higher values mean fewer selected static patterns were observed. This is not a security score or safety probability. capabilityScore is null whenever evidence-grade analysis is unavailable.
Parameters
address(path, required) — Base smart contract address (20-byte hexadecimal, checksummed or lowercase)
Documented responses
200— Score and deduction breakdown400— Malformed input401— Missing or invalid credential, or a credential was supplied in the query string402— No credential supplied for a payable route, or the issuance-anchored 31-day credit allowance is exhausted429— A plan burst limit or bounded public/intent retry limit was exceeded503— A required dependency is unavailable; the request failed closed
GET/v1/gas/feesObserved Base gas price
Access: API key in x-api-key OR API key in Authorization: Bearer OR Settled x402 payment
Observed Base gas price
Documented responses
200— Gas observation with provenance401— Missing or invalid credential, or a credential was supplied in the query string402— No credential supplied for a payable route, or the issuance-anchored 31-day credit allowance is exhausted429— A plan burst limit or bounded public/intent retry limit was exceeded503— The upstream data source is unavailable. No value is returned rather than an estimated one.
GET/v1/dex/metricsAggregate DEX liquidity and volume for tracked Base tokens
Access: API key in x-api-key OR API key in Authorization: Bearer OR Settled x402 payment
The coverage object states exactly which tokens were aggregated. This is not a whole-chain total.
Documented responses
200— Aggregate with coverage and provenance401— Missing or invalid credential, or a credential was supplied in the query string402— No credential supplied for a payable route, or the issuance-anchored 31-day credit allowance is exhausted429— A plan burst limit or bounded public/intent retry limit was exceeded503— The upstream data source is unavailable. No value is returned rather than an estimated one.
GET/v1/token/price/{symbol}Liquidity-weighted Base token price
Access: API key in x-api-key OR API key in Authorization: Bearer OR Settled x402 payment
Median of the five deepest indexed pools, so a single manipulated pool cannot move the published price. Unknown symbols return 404 with the supported list; a price is never guessed.
Parameters
symbol(path, required)
Documented responses
200— Priced token with provenance401— Missing or invalid credential, or a credential was supplied in the query string402— No credential supplied for a payable route, or the issuance-anchored 31-day credit allowance is exhausted404— Symbol is not tracked429— A plan burst limit or bounded public/intent retry limit was exceeded503— The upstream data source is unavailable. No value is returned rather than an estimated one.
GET/v1/whales/signalsLarge ERC-20 transfers observed on Base
Access: API key in x-api-key OR API key in Authorization: Bearer OR Settled x402 payment
Sourced from eth_getLogs over a bounded recent block range and valued using live pool prices. ERC-20 Transfer events only.
Documented responses
200— Observed signals with the exact query window401— Missing or invalid credential, or a credential was supplied in the query string402— No credential supplied for a payable route, or the issuance-anchored 31-day credit allowance is exhausted429— A plan burst limit or bounded public/intent retry limit was exceeded503— The upstream data source is unavailable. No value is returned rather than an estimated one.
GET/v1/keys/selfMetadata for the presented key
Access: API key in x-api-key OR API key in Authorization: Bearer
Requires an API key; an x402 payment cannot access this route. The raw key is never echoed.
Documented responses
200— Key metadata401— Missing or invalid credential, or a credential was supplied in the query string402— No credential supplied for a payable route, or the issuance-anchored 31-day credit allowance is exhausted429— A plan burst limit or bounded public/intent retry limit was exceeded503— A required dependency is unavailable; the request failed closed
POST/v1/keys/revokePermanently revoke the presented key
Access: API key in x-api-key OR API key in Authorization: Bearer
Permanently revoke the presented key
Request body (required): application/json. See the OpenAPI contract for the complete schema.
Documented responses
200— Revoked400— Malformed input401— Missing or invalid credential, or a credential was supplied in the query string402— No credential supplied for a payable route, or the issuance-anchored 31-day credit allowance is exhausted429— A plan burst limit or bounded public/intent retry limit was exceeded503— A required dependency is unavailable; the request failed closed
POST/v1/keys/recovery/challengeCreate a non-enumerating paid-key recovery challenge
Access: No route-level credential. Additional wallet, session or operator conditions may apply as described below.
Returns the same 202 envelope for known and unknown wallets. An optional original subscription txHash bootstraps legacy paid keys. Free and revoked keys cannot be recovered.
Request body (required): application/json. See the OpenAPI contract for the complete schema.
Documented responses
202— Structurally identical real or decoy challenge400— Malformed input429— A plan burst limit or bounded public/intent retry limit was exceeded503— A required dependency is unavailable; the request failed closed
POST/v1/keys/recovery/claimRotate a paid API key with its subscriber-wallet signature
Access: No route-level credential. Additional wallet, session or operator conditions may apply as described below.
Atomically revokes the previous secret and returns a replacement exactly once. The tier and expiration are preserved.
Request body (required): application/json. See the OpenAPI contract for the complete schema.
Documented responses
200— Replacement key issued and previous key revoked400— Malformed input401— Missing or invalid credential, or a credential was supplied in the query string409— Challenge already consumed or target changed429— A plan burst limit or bounded public/intent retry limit was exceeded503— A required dependency is unavailable; the request failed closed
POST/mcpCurrent MCP Streamable HTTP endpoint
Access: No route-level credential. Additional wallet, session or operator conditions may apply as described below.
Processes one MCP JSON-RPC request, notification, or response per POST. Negotiates the current 2026-07-28 protocol and stateless 2025-era clients. Tool execution enforces API-key or x402 access at the API layer.
Request body (required): application/json. See the OpenAPI contract for the complete schema.
Documented responses
200— MCP JSON-RPC response as JSON or an SSE response stream, according to protocol negotiation202— MCP notification or response accepted with no response message400— Malformed input403— Origin rejected406— Required MCP response content type was not accepted
GET/mcpOpen an MCP server event stream when negotiated
Access: No route-level credential. Additional wallet, session or operator conditions may apply as described below.
The current MCP endpoint may open an SSE stream for server messages. Stateless clients with no listenable stream receive 405.
Documented responses
200— MCP event stream405— No event stream is available for this stateless request
GET/sseLegacy MCP HTTP+SSE stream
Access: No route-level credential. Additional wallet, session or operator conditions may apply as described below.
Compatibility endpoint for protocol 2024-11-05 clients. New clients use the single /mcp Streamable HTTP endpoint.
Documented responses
200— SSE event stream
POST/messagesLegacy MCP HTTP+SSE JSON-RPC message handler
Access: No route-level credential. Additional wallet, session or operator conditions may apply as described below.
Compatibility message endpoint paired with /sse for protocol 2024-11-05 clients. New clients POST to /mcp.
Request body (required): application/json. See the OpenAPI contract for the complete schema.
Documented responses
200— MCP JSON-RPC response
GET/v1/samplesIndex of free response samples
Access: No route-level credential. Additional wallet, session or operator conditions may apply as described below.
Lists the free, frozen examples of each paid response. Published so an agent can read the exact schema of a paid route before spending anything.
Documented responses
200— Sample index
GET/v1/sampleFree frozen example of a paid response
Access: No route-level credential. Additional wallet, session or operator conditions may apply as described below.
A structurally complete example of one paid response, captured from the same code path the paid route uses. Free and never payment-gated. The values are not current: the payload is nested under response and the envelope carries sample: true and capturedAt so a snapshot can never be mistaken for live data. Frozen rather than live for two reasons: a live preview of gas, price or liquidity data would give away the thing being sold, and a sample that calls an upstream provider can fail, which would mark the listing failing in directories that re-probe it.
Parameters
name(query, required) — Which paid response to preview.
Documented responses
200— Frozen sample404— No sample by that name
4. Understand the evidence
Static selected-pattern observations do not establish safety, maliciousness, exploitability or reachability. Preserve notASafetyGuarantee: true, reachability: "NOT_ESTABLISHED" and limitations when you pass results to another system.
4-Step Agent Policy-Pipeline Architecture
- Observed facts: PUSH-aware opcodes and selectors, resolved targets and provenance.
- Capability implication: understand an observed pattern without assuming runtime reachability.
- Consumer policy: compare the evidence and unknown states with caller-defined requirements.
- Consumer action: the caller owns the execution decision. The API does not issue transaction permission.
RPC Trust Hierarchy & Quorum Consensus
HIGH_TRUST_PRIMARY- Credentialed TLS 1.3 RPC with Base chain ID 8453 validation. Evidence quality is still subject to the returned verdict and limitations.
QUORUM_PUBLIC- Agreement across at least two independent public RPC nodes.
DEGRADED_LOW_TRUST- A lone public response without quorum. Evidence grade is false.
UNTRUSTED_INSECURE- Insecure or invalid-chain evidence cannot be promoted into trusted output.
Deterministic Reproducibility Metadata
Runtime and implementation SHA-256 hashes support independent bytecode comparison. A matching hash is not a proof that a capability is reachable or that a transaction is safe. Unresolved proxy/delegation paths remain explicit.
Reproducible Benchmark Modes
Hermetic engine microbenchmark: uses local fixtures and mock RPC. It does not measure live chain accuracy or network latency.
Live Base RPC benchmark: measures the complete provider path, agreement, block drift and failures in a specific environment. There is no universal response-time guarantee.
Read the published benchmark artifact or see the methodology on the validation page.
Reference integration: a pre-signing boundary
Fetch evidence for the intended target, examine its trust grade and unresolved execution paths, then apply your own application policy before signing. A detected pause or freeze selector alone cannot establish whether a transfer will revert.
On-chain metadata attestation
The published EAS record is a metadata snapshot, not a safety certification or live availability guarantee.
For crawlers and agents
Fetch the contract or plain-text guide directly. JavaScript execution, screenshots and paid calls are not required to discover how the API works.