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.
LiveAuthentication
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:
| 401 | INVALID_KEY | Missing or invalid API key. |
| 400 | MISSING_PARAM | A required field or identifier is missing. |
| 400 | MISSING_QUERY | POST /v1/ask without query. |
| 400 | MISSING_TYPE | POST /v1/get_data without type. |
| 400 | MISSING_POLICY | policy.maxPriceImpactBps is required (preflight, gate). There is no server-side default. |
| 400 | BAD_MIN_LEVEL | minLevel is not a level this route accepts. |
| 400 | BAD_TRANSACTION / BAD_INTENT / BAD_POLICY / BAD_PARAM | A preflight field is malformed. The message says which. |
| 400 | WATCH_REJECTED | Unsupported type, params or webhookUrl for a watch. |
| 402 | NO_CREDITS | Preflight: the balance is below the fee of a delivered verdict. Checked before any work. |
| 402 | INSUFFICIENT_CREDITS | Data calls: the balance does not cover the call. |
| 403 | TEST_MODE_NOT_SUPPORTED | Preflight with an mk_test_ key. It verifies live chain state; use a live key. |
| 404 | TYPE_NOT_FOUND | Unknown or unservable data type. |
| 409 | NO_QUALIFYING_DELIVERY | Data calls: no delivery met the level you required. Nothing charged. |
| 429 | RATE_LIMIT | Over your plan’s rate. retryAfterSeconds says when to retry. |
| 500 | DECISION_LOG_UNAVAILABLE | Preflight: the verdict could not be recorded, so it was not delivered. Nothing charged; retry. |
| 500 | PREFLIGHT_FAILED | Preflight 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.
