Build

API reference

One base URL, one header, three endpoints.

Base URL https://api.metera.xyz. Auth by Authorization: Bearer mk_live_… (or x-api-key).

GET /v1/types

The servable catalog: the canonical types live today, with the max level each reaches.

{
  "types": [
    { "type": "token.price", "providers": 4, "requiredParams": [], "maxLevel": "anchored", "capReason": null },
    { "type": "social.value", "providers": 1, "requiredParams": ["handle","user_id"], "maxLevel": "single_source",
      "capReason": "one provider, no independent peer; served as single_source only" }
  ]
}

POST /v1/ask

Body { "query": string }. A model classifies the question into a canonical type, it never answers from its own knowledge. Returns the delivery shape, or no_source for anything no feed measures.

// non-measurable question -> honest no_source (HTTP 200, nothing charged)
{ "status": "no_source",
  "message": "No source measures that. Metera answers from data feeds (prices, social metrics, live counts), not general knowledge." }

POST /v1/get_data

Body { "type": string, "params": object }. Direct canonical call, no model in the path.

curl -X POST https://api.metera.xyz/v1/get_data \
  -H "Authorization: Bearer mk_live_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"type":"social.value","params":{"handle":"charlidamelio"}}'

The delivery object

Field by field, this is the product surface.

{
  "status": "delivered",          // delivered | no_source | refused | error
  "data": { ... },                // the datum (shape depends on the type)
  "verification": {
    "level":   "anchored",        // single_source | consensus | anchored
    "source":  "bitstamp",        // the source that delivered
    "cost":    "0.0015",          // engine-internal charged amount, informational
    "traceId": "tr_elxvqz"        // audit id for this decision
  },
  "type":   "token.price",
  "params": { "token": "SOL" },
  "debitedCredits": 1,            // what YOU are billed, in credits
  "balanceAfter":   2999          // your remaining credit balance
}

Error codes

401  INVALID_KEY              { "error":"Missing or invalid API key", "code":"INVALID_KEY" }
400  MISSING_QUERY            query is required (/v1/ask)
400  MISSING_TYPE             type is required (/v1/get_data)
404  TYPE_NOT_FOUND           { "error":"Unknown or unservable type", "code":"TYPE_NOT_FOUND" }
400  MISSING_PARAM            found a source but the identifier is missing (e.g. social handle)
402  INSUFFICIENT_CREDITS     { "status":"error", "code":"INSUFFICIENT_CREDITS", "balance": 0 }
409  NO_QUALIFYING_DELIVERY   refused: no delivery met the required level, nothing charged
429  RATE_LIMIT               { "error":"Rate limit: 10/min", "code":"RATE_LIMIT" }
500  RESOLVE_FAILED           internal resolve error

// no_source is a 200, not an error. It is the honest answer.

PreviousVerification levels

NextMCP