Routavo

Find APIs on the Routavo network that can perform a capability. Returns each provider with its published price, measured latency, terms, and the exact argument schema for calling it, plus the rule Routavo uses to pick between them. Call this before call() when you do not already know a provider id.

{
  "type": "object",
  "properties": {
    "capability": {
      "type": "string",
      "description": "What you need done, e.g. \"geocode\" or \"forecast\". Omit to list everything."
    },
    "query": {
      "type": "string",
      "description": "Free text when you do not know the capability name, e.g. \"turn an address into coordinates\" or \"will it rain tomorrow\". Matched against names, aliases, tags and descriptions; results come back ranked with a score."
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "providers": {
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "count": {
      "type": "integer"
    },
    "routing": {
      "type": "object"
    }
  },
  "required": [
    "providers",
    "count",
    "routing"
  ]
}

Route a call to the Routavo network, meter it, and return the result. Give either a provider id from discover(), or a capability and let Routavo pick using its published routing rule. Optional max_price and max_latency_ms constrain the choice. Failed calls are recorded but cost nothing.

{
  "type": "object",
  "properties": {
    "provider": {
      "type": "string",
      "description": "Provider id, e.g. \"open-meteo.geocode\". Omit to route by capability.",
      "x-mcp-header": "Provider"
    },
    "capability": {
      "type": "string",
      "description": "Capability to route on, e.g. \"geocode\". Ignored when provider is given."
    },
    "arguments": {
      "type": "object",
      "description": "Arguments in the capability contract shape from discover(). Learn geocode once; every provider behind it takes the same input and returns the same output.",
      "additionalProperties": true
    },
    "max_price": {
      "type": "string",
      "description": "Do not route above this price per call, e.g. \"0.0030\""
    },
    "max_latency_ms": {
      "type": "integer",
      "description": "Do not route to a provider slower than this p50"
    },
    "country": {
      "type": "string",
      "description": "Two letter code for where this request is, e.g. \"FR\". A routing hint, not an argument to the API: it lets a provider that covers only that country be chosen, and keeps one that does not out of the running. Unnecessary when the arguments already carry coordinates."
    },
    "dry_run": {
      "type": "boolean",
      "description": "Quote only: which provider would be chosen, at what price, with what latency, and why. Nothing is called, charged or counted."
    },
    "wallet": {
      "type": "string",
      "description": "Your wallet address, asserted. Attributes metering and a daily cap on the free tier; it proves nothing. To pay from a balance, prove the wallet once at /api/wallet and send the key it returns as wallet_key or as Authorization: Bearer rw_...",
      "x-mcp-header": "Wallet"
    },
    "wallet_key": {
      "type": "string",
      "description": "A wallet key (rw_...) from /api/wallet. Proves the wallet, and calls are paid from its deposited USDC balance. Prefer sending it as the Authorization: Bearer header."
    },
    "payment": {
      "type": "object",
      "description": "Pay this one call with x402: { rail: \"x402\", payload: <PaymentPayload> }, an EIP-3009 authorization to the pay-to address for at least the price, signed by your wallet. The requirements to sign are in discover() and in any payment_required error. A facilitator verifies and settles it; the receipt carries the transaction.",
      "properties": {
        "rail": {
          "type": "string"
        },
        "payload": {
          "type": "object"
        }
      },
      "additionalProperties": false
    },
    "plan": {
      "type": "array",
      "description": "Instead of one call, a sequence of up to 8 steps: [{ id, capability | provider, arguments, max_price?, max_latency_ms? }]. A later step may take a value from an earlier one with { \"$ref\": \"<step id>.output.<path>\" }, e.g. { \"$ref\": \"geo.output.results[0].lat\" }. The whole plan is quoted before anything runs; with dry_run it is only quoted. Steps run in order and stop at the first failure. Each step returns its own receipt and the response carries one total.",
      "items": {
        "type": "object"
      },
      "maxItems": 8
    },
    "max_total": {
      "type": "string",
      "description": "For a plan: do not run if the quoted total exceeds this, e.g. \"0.0100\"."
    },
    "budget": {
      "type": "object",
      "description": "A task budget: { id, max }. Spend under this id is tracked across any number of calls, plans and batches, and a call that would take it past max is refused with code \"budget\". { id, statement: true } returns what the budget has spent and the receipts behind it.",
      "properties": {
        "id": {
          "type": "string"
        },
        "max": {
          "type": "string"
        },
        "statement": {
          "type": "boolean"
        }
      },
      "additionalProperties": false
    },
    "recipe": {
      "type": "string",
      "description": "A named, published plan, e.g. \"weather_for_place\". Give its arguments and it runs the steps for you, quoted first, with the last step's output on top. discover() lists recipes with their inputs and estimated price."
    },
    "batch": {
      "type": "array",
      "maxItems": 50,
      "items": {
        "type": "object"
      },
      "description": "Instead of one arguments object, up to 50 of them for the same capability or provider. Run in parallel, each with its own receipt, one total. Failed items cost nothing and do not stop the others."
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Return only these output paths, e.g. [\"results.name\", \"results.lat\", \"results.lng\"]. Saves tokens; the receipt still hashes the full answer."
    },
    "idempotency_key": {
      "type": "string",
      "description": "Your own id for this call, up to 64 characters. A retry with the same key within 24 hours returns the same result and receipt and is never charged again. The output is kept for those 24 hours only because you asked for replay."
    },
    "failover": {
      "type": "boolean",
      "description": "Default true when routing by capability: if the chosen provider fails, the next eligible one is tried and only the one that answered is charged. Set false to fail fast."
    },
    "quorum": {
      "type": "integer",
      "minimum": 2,
      "maximum": 3,
      "description": "Ask 2 or 3 providers the same question and get an agreement score with every answer. Each provider is charged. Refused if fewer providers clear your constraints, so quote it first with dry_run."
    }
  },
  "additionalProperties": false
}

Check a receipt returned by call(). Confirms the signature, so the provider, price, fee, and the hashes of what went in and came out are exactly what Routavo recorded. Works for anyone holding the receipt. Reveals nothing else.

{
  "type": "object",
  "properties": {
    "receipt": {
      "type": "object",
      "description": "The receipt object from a call() result.",
      "additionalProperties": true
    }
  },
  "required": [
    "receipt"
  ],
  "additionalProperties": false
}

Flag a metered call for the provider to review. Takes the receipt and a short reason. The receipt must verify and must have charged something. The dispute lands in that provider's queue and is visible to Routavo. One dispute per receipt.

{
  "type": "object",
  "properties": {
    "receipt": {
      "type": "object",
      "description": "The receipt object from the call() result you are disputing.",
      "additionalProperties": true
    },
    "reason": {
      "type": "string",
      "description": "What was wrong, in plain words. Up to 500 characters. Do not paste the response body."
    }
  },
  "required": [
    "receipt",
    "reason"
  ],
  "additionalProperties": false
}