Route Viability API

Who this API is for

The Route Viability API is designed for teams that need structured, evidence-based crypto fee data — not opinions or recommendations.

What you can build with it

• Exchange comparison widgets — embed fee range data for a specific country and payment method, with freshness timestamps and provenance
• Route coverage checks — determine whether a country/asset/rail combination has verified cost data before showing it to users
• Fee monitoring dashboards — poll periodically to track how exchange fee ranges change over time for specific routes
• Data quality audits — use freshness buckets and verification levels to assess data reliability before incorporating into downstream systems

The API returns structured data with explicit provenance. How you present it to your users is your decision — Augea does not control downstream display or interpretation.

Evaluate the API

During beta, you can evaluate the API before committing to integration:

1. Request a beta key — email api@augea.io with your use case and target markets
2. Test with real queries — try the markets you care about and inspect response quality, freshness, and coverage depth
3. Check coverage fit — verify that the countries, assets, and rails you need are covered, and that enough exchanges are rankable for your use case
4. Review provenance — every response includes snapshot IDs, capture timestamps, and freshness buckets so you can assess data age and reliability

There is no commitment required during beta. No billing, no minimum volume, no lock-in.

Quick start

Try it with a single request. Replace YOUR_KEY with your beta API key.

curl -H "Authorization: Bearer YOUR_KEY" \
  "https://augea.io/api/agent/route-viability?country=US&asset=BTC&rail=card"

Returns a JSON response with every exchange in the catalog, their viability state, fee ranges where available, freshness buckets, and snapshot provenance. No API key yet? Contact api@augea.io to request beta access.

What this API does

Given a country, asset, and payment rail, the Route Viability API returns which exchanges in Augea's catalog have coverage for that route — and what the coverage quality looks like.

Every exchange in the catalog appears in the response. Each entry carries a viabilityState that reflects how much Augea knows about that exchange on this route: fee data verified and rankable, a snapshot row present but incomplete, or no data at all. Unknown is a valid first-class state — not an error.

Authentication

All requests require a bearer token in the Authorization header.

Authorization: Bearer <your-api-key>

API keys are provisioned manually during the beta period. A missing or invalid key returns 401 UNAUTHORIZED. A disabled key returns the same 401 — no information is leaked about whether a key exists but is disabled versus never existed.

Endpoint

GET /api/agent/route-viability

All three parameters are required. Missing or invalid params return 400 INVALID_REQUEST.

Example request

curl "https://augea.io/api/agent/route-viability?country=US&asset=BTC&rail=card" \
  -H "Authorization: Bearer <your-api-key>"

Success response (200)

Returns 200 with a RouteViabilityResponseV1 body. Abbreviated example (actual response includes all tracked exchanges):

{
  "version": "augea-route-viability.v1",
  "generatedAt": "2025-03-17T20:00:00.000Z",
  "request": { "country": "US", "asset": "BTC", "rail": "card" },
  "routeSummary": {
    "totalExchangeCount": 16,
    "rankableCount": 9,
    "trackingCount": 4,
    "noDataCount": 3,
    "hasViableRoute": true
  },
  "exchanges": [
    {
      "exchangeSlug": "coinbase",
      "exchangeName": "Coinbase",
      "viabilityState": "rankable",
      "rankable": true,
      "feeRange": { "low": 1.49, "high": 3.99 },
      "freshnessBucket": "FRESH",
      "snapshotId": "1234",
      "capturedAt": "2025-03-17T10:00:00.000Z",
      "verificationLevel": "script_verified",
      "unknownReason": null
    },
    {
      "exchangeSlug": "gemini",
      "exchangeName": "Gemini",
      "viabilityState": "tracking",
      "rankable": false,
      "feeRange": null,
      "freshnessBucket": "DEGRADED",
      "snapshotId": "1234",
      "capturedAt": "2025-03-10T10:00:00.000Z",
      "verificationLevel": "partial",
      "unknownReason": "Snapshot present but fee data insufficient for ranking"
    },
    {
      "exchangeSlug": "robinhood",
      "exchangeName": "Robinhood",
      "viabilityState": "no_data",
      "rankable": false,
      "feeRange": null,
      "freshnessBucket": null,
      "snapshotId": null,
      "capturedAt": null,
      "verificationLevel": null,
      "unknownReason": "No snapshot data for this route"
    }
  ],
  "provenance": {
    "snapshotId": "1234",
    "snapshotCreatedAt": "2025-03-17T18:00:00.000Z",
    "freshnessBucket": "FRESH",
    "audit": {
      "noInference": true,
      "unknownsFirstClass": true,
      "contractVersion": "v1"
    }
  },
  "responseGuidance": {
    "allowedUses": [
      "Determine whether a route is covered by Augea data",
      "List which exchanges have verifiable cost data for a route",
      "Surface fee range estimates alongside freshness and provenance"
    ],
    "forbiddenUses": [
      "Recommend or rank exchanges as 'best' or 'safest'",
      "Present fee ranges as guaranteed quotes",
      "Infer exchange quality or safety from viability state"
    ]
  }
}

Error responses

{
  "version": "augea-route-viability.v1",
  "ok": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Valid API key required. Provide: Authorization: Bearer <key>"
  }
}

HTTP/2 429
Retry-After: 42

{
  "version": "augea-route-viability.v1",
  "ok": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 42 seconds."
  }
}

{
  "version": "augea-route-viability.v1",
  "ok": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "rail must be one of: card, bank"
  }
}

Per-exchange entry fields (exchanges[])

Every exchange in Augea's catalog appears in the exchanges array — including those with no data. The array is not filtered.

Route summary fields (routeSummary)

Provenance (provenance)

Every response includes a provenance block that identifies the snapshot the data was derived from and the freshness of that snapshot. This lets consumers reason about data age without inspecting individual exchange entries.

Freshness semantics

Freshness buckets are derived from the capturedAt timestamp of each evidence row using canonical thresholds:

These thresholds are canonical across Augea's data pipeline and will not change within v1.

Supported markets (beta)

The API currently covers the following markets. Coverage expands over time. Queries outside these markets return UNSUPPORTED_SCENARIO (404).

33 exchanges are tracked across these markets. Not every exchange supports every market combination. The API returns the full catalog with per-exchange viability states.

Versioning

The response carries a version: "augea-route-viability.v1" field. Within v1, the contract is additive-only: new fields may be added, but existing fields will not be removed or renamed without a version bump. Consumers should tolerate unknown fields.

The same versioning applies to error responses — the version field is present on both success and error shapes.

Rate limits (beta)

The current rate limit is 60 requests per minute per API key, enforced with a sliding window. This is a per-instance limit — Augea runs on serverless infrastructure and rate limit state is not shared across instances. At low beta traffic volumes, this is sufficient. Limits will evolve before general availability.

On 429, the response includes a Retry-After header with the number of seconds until the oldest request in the window expires.

Beta access

The Route Viability API is in beta. To request access, contact api@augea.io with:

• What you are building and who your users are
• Which markets (countries, assets, rails) you need
• Expected query volume

Pricing will be announced before general availability. There is no charge and no commitment during the beta period.