Live today

API reference

Every route served at https://api.metera.xyz today: what it takes, what it returns, what it charges, and how it fails.

Live

Authentication

Send your key on every request as Authorization: Bearer YOUR_API_KEY(x-api-key: YOUR_API_KEY also works). mk_live_ keys call real sources and are billed. mk_test_ keys return fixtures of the same shape for the data routes and charge nothing; the preflight refuses them. Keys are created at metera.xyz/dashboard/api-keys.

Rate limits are per plan (Free 10 requests a minute) and answer 429. Credits: 1 credit = $0.001, billed on delivery only. See pricing.

Preflight

POST /v1/preflight

Verifies the exact transaction before it is signed. Body:

{
  "transaction": "<base64: legacy or v0, signed or not>",
  "intent": {
    "pool": "<Raydium CPMM or Meteora DAMM V2 pool>",
    "taker": "<the fee payer / signer>",
    "outputMint": "<the mint you expect to receive>",
    "direction": "exact_in" | "exact_out",
    "minOut": "<raw units, optional>",
    "outcome": { "maxSpend": { "<mint|SOL>": "<raw>" }, "minReceive": { "<mint|SOL>": "<raw>" } }
  },
  "policy": {
    "maxPriceImpactBps": 50,
    "maxRiskScore": 70,
    "maxSlotsStale": 2,
    "minLevel": "single_source" | "consensus",
    "maxUndeclaredLamports": "0",
    "maxNotional": "<raw units of the input mint>",
    "allowedMints": [], "deniedMints": [], "allowedPrograms": []
  },
  "candidateTransaction": "<base64, optional>",
  "reverifyAmountOutDeltaBps": 0,
  "jupiterQuote": { "inAmount": "…", "outAmount": "…", "otherAmountThreshold": "…", "slippageBps": 50, "routePlan": [] }
}

Only transaction, intent.pool, intent.taker, intent.outputMint, intent.direction and policy.maxPriceImpactBps are required. maxRiskScore adds a token-risk check, billed separately, run only when the chain facts have not already refused.

Response, HTTP 200 for every verdict, refuse included:

{
  "decision": "allow" | "allow_with_caveat" | "refuse",
  "decision_id": "<decision log row>",
  "message_hash": "sha256:…",
  "consensus_reasons": [{ "layer": "…", "reason": "…" }],
  "policy_reasons": [{ "source": "policy" | "layer_flag", "field": "…", "reason": "…", "tripped": true }],
  "checks": [{ "id": "26", "status": "pass" | "fail" | "…" }],
  "scope": { "covers": [], "doesNotCover": [] },
  "receipt": { "receipt": { … }, "alg": "Ed25519", "signature": "<base64>" },
  "receipt_unavailable": "<only when receipt is null: why>",
  "proof": { … },
  "billing": { … },
  "debitedCreditsTotal": 0
}
  • consensus_reasons: chain facts. Any one refuses; no policy overrides it.
  • policy_reasons with tripped: true: your threshold crossed, so refuse. tripped: false: a flag for you to decide on, so a caveat.
  • Charged only for a delivered allow or allow_with_caveat. A refuse is free.
  • Also as the MCP tool preflight_transaction, same body and response.

Receipts

GET /v1/receipts/keys · no key needed

GET /.well-known/metera-receipt-keys.json · no key needed

{
  "issuer": "api.metera.xyz",
  "keys": [{ "key_id": "ed25519:1886527ed07c735b", "alg": "Ed25519",
             "public_key": "Ylu2TPFCjooUOsm8oz9MbL9kK7/ruOUZwn1xGggqKu8=", "status": "active" }]
}

Retired keys stay listed with status: "retired". How to verify: Receipts.

Swap gate

POST /v1/gate

{
  "pool": "<Raydium CPMM or Meteora DAMM V2 pool>",
  "payer": "<wallet>",
  "inputTokenAccount": "<account>",
  "outputTokenAccount": "<account>",
  "amountIn": "<raw units>",
  "policy": { "maxPriceImpactBps": 100, "maxRiskScore": 70, "maxSlotsStale": 2, "minLevel": "single_source" | "consensus" | "anchored" }
}

Composes a token-risk check and a simulated swap quote into allow, allow_with_caveat or refuse, by your policy. Returns the verdict and debitedCreditsTotal, the sum of the two checks. Nothing is signed or sent. MCP tool: evaluate_gate.

Verified data

GET /v1/types

The live catalog: every servable type, its required params, and the highest level it reaches.

{ "types": [{ "type": "spot.price", "providers": 4, "requiredParams": ["symbol"], "maxLevel": "consensus", "capReason": null }] }

POST /v1/get_data

{ "type": "spot.price", "params": { "symbol": "BTC" }, "minLevel": "consensus", "requireOnChainAnchor": false }

POST /v1/ask

{ "query": "SOL price" }

Both answer with the same delivery object:

{
  "status": "delivered",
  "data": { "token": "SOL", "priceUsd": 73.584, "asOf": 1785892950013 },
  "verification": { "level": "anchored", "source": "bitstamp", "cost": "0.0015", "traceId": "tr_elxvqz" },
  "type": "token.price",
  "params": { "token": "SOL" },
  "debitedCredits": 1,
  "balanceAfter": 2999
}

status: "no_source" (HTTP 200) when no feed measures the question; refused (HTTP 409) when nothing met minLevel. Neither is charged. MCP tools: get_verified_data, list_available_data, get_trace.

Watches and webhooks

POST /v1/watch

{
  "type": "solana.pool_state",
  "params": { "pool": "<pool address>" },
  "condition": { "field": "…", "changes": true } | { "field": "…", "crosses": 1.5, "direction": "below" | "above" },
  "webhookUrl": "https://your.app/hooks/metera",
  "minIntervalSeconds": 60
}

Watchable types and the param that names the address: solana.pool_state (pool), solana.token_risk (address), solana.resolve_address (address), solana.can_sign (target), solana.token_account_owner (account).

Answers 201 with id, watchedAddress and webhookSecret, shown once. A change never is the answer: it wakes a fresh verification, billed like a normal call, delivered as:

{ "event": "watch.fired", "watchId": "…", "type": "…", "params": { … }, "value": { … }, "traceId": "…", "firedAt": "…", "signature": "<hex>" }

To verify a delivery: remove signature, serialize the rest as canonical JSON (keys sorted at every level, no whitespace), HMAC-SHA256 it with your webhookSecret, and compare the hex in constant time. Each delivery is attempted once; a missed one can be read with the MCP tool poll_watch.

GET /v1/watch

DELETE /v1/watch/{id}

MCP

POST /mcp

Streamable HTTP, same key as a bearer header, or OAuth from an app. Nine tools: preflight_transaction, evaluate_gate, get_verified_data, list_available_data, get_trace, create_watch, list_watches, delete_watch, poll_watch. See MCP.

Not enabled yet

POST /v1/execute, GET /v1/executions/{id} and /v1/signer/* are built but not enabled on api.metera.xyz: they answer 404. They are documented when they open. See Execution.

Errors

Errors are JSON with error (a message) and code:

401INVALID_KEYMissing or invalid API key.
400MISSING_PARAMA required field or identifier is missing.
400MISSING_QUERYPOST /v1/ask without query.
400MISSING_TYPEPOST /v1/get_data without type.
400MISSING_POLICYpolicy.maxPriceImpactBps is required (preflight, gate). There is no server-side default.
400BAD_MIN_LEVELminLevel is not a level this route accepts.
400BAD_TRANSACTION / BAD_INTENT / BAD_POLICY / BAD_PARAMA preflight field is malformed. The message says which.
400WATCH_REJECTEDUnsupported type, params or webhookUrl for a watch.
402NO_CREDITSPreflight: the balance is below the fee of a delivered verdict. Checked before any work.
402INSUFFICIENT_CREDITSData calls: the balance does not cover the call.
403TEST_MODE_NOT_SUPPORTEDPreflight with an mk_test_ key. It verifies live chain state; use a live key.
404TYPE_NOT_FOUNDUnknown or unservable data type.
409NO_QUALIFYING_DELIVERYData calls: no delivery met the level you required. Nothing charged.
429RATE_LIMITOver your plan’s rate. retryAfterSeconds says when to retry.
500DECISION_LOG_UNAVAILABLEPreflight: the verdict could not be recorded, so it was not delivered. Nothing charged; retry.
500PREFLIGHT_FAILEDPreflight could not complete. Nothing charged.

Refusals are not errors

A preflight refuse is HTTP 200 with its reasons. A data refused is HTTP 409. Do not retry a refusal hoping for a different answer.

Base URL https://api.metera.xyz. JSON in, JSON out. Amounts are base-10 strings of raw units.