VIQL — vehicle-eligibility API

A paid HTTP endpoint that answers one question with a cited verdict: can this specific licensed, insured vehicle take this kind of trip? Operated by upgo.ai inc. Fleet and credential data belong to Volt and Velvet Mobility LLC, a TCP-licensed California charter-party carrier (TCP 51207-B).

Payment is the only admission: the first request returns HTTP 402 with machine-readable payment requirements; a request carrying a valid signed payment returns the verdict. There is no signup and no prior contact with us required. Anything on this page can be verified before paying — the 402 quote below is retrievable with one curl.

Query parameters

How payment works (x402)

1. Call the endpoint with no X-PAYMENT header. The response is HTTP 402 with a JSON body whose accepts[0] is:

   {
     "scheme":            "exact",
     "network":           "base",
     "maxAmountRequired": "100000",
     "resource":          "https://qwtw9n75u0.execute-api.us-east-1.amazonaws.com/v1/viql/vvm/paid/vehicle/eligibility",
     "description":       "Cited compliance eligibility verdict (checks[] + ledger provenance)",
     "mimeType":          "application/json",
     "payTo":             "0x8C2d7c8495245c25De74C900aF7057f1608A19F8",
     "maxTimeoutSeconds": 60,
     "asset":             "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
     "extra":             { "name": "USD Coin", "version": "2" }
   }

   100000 is atomic USDC units (6 decimals) = 0.10 USDC. asset is the USDC contract on Base mainnet.
2. Sign an EIP-3009 transferWithAuthorization for that amount to payTo, from a wallet holding USDC on Base. No ETH is needed — settlement is broadcast by the facilitator, not by you. The x402 client libraries below do this signing for you.
3. Retry the same request with X-PAYMENT: <base64 of the signed payment payload>. This endpoint speaks x402 v1: the request header is X-PAYMENT, not v2's PAYMENT-SIGNATURE, and the 402 body uses v1 field names (maxAmountRequired, plain base network id). Current reference clients handle both versions; a v2-only client that sends PAYMENT-SIGNATURE will not be recognized here.
4. The server verifies the payment cryptographically (Coinbase CDP facilitator), computes the verdict, settles the transfer on-chain, and only then responds 200. The response carries X-PAYMENT-RESPONSE: a base64 settlement receipt including the transaction hash.

Billing rules, exactly as implemented:

• A malformed request (400) is never charged — parameters are validated before settlement.
• Settlement precedes the response body. If settlement fails, the verdict is withheld (402) — there are no free verdicts on this route.
• The 402 body is the authoritative quote at call time. If this page and a live 402 ever disagree, the 402 is correct.

Copy-pasteable example

Inspect the quote first — costs nothing, requires nothing:

curl -i "https://qwtw9n75u0.execute-api.us-east-1.amazonaws.com/v1/viql/vvm/paid/vehicle/eligibility?airport=OAK&passengers=4"
# → HTTP/2 402 + the accepts[] payment requirements shown above

Paid call (Node 18+; wallet key holds ≥ 0.10 USDC on Base mainnet, zero ETH required):

// npm install x402-fetch viem
import { privateKeyToAccount } from "viem/accounts";
import { wrapFetchWithPayment } from "x402-fetch";

const account = privateKeyToAccount(process.env.WALLET_PRIVATE_KEY);
const payFetch = wrapFetchWithPayment(fetch, account);

const res = await payFetch(
  "https://qwtw9n75u0.execute-api.us-east-1.amazonaws.com/v1/viql/vvm/paid/vehicle/eligibility"
  + "?airport=OAK&passengers=4"
);

console.log(res.status);                              // 200
console.log(res.headers.get("x-payment-response"));   // base64 settlement receipt (tx hash)
console.log(await res.json());                        // the cited verdict

Python equivalent: the x402 package on PyPI wraps httpx/requests the same way.

What you get back

Schema vehicle-eligibility/v1. eligible is never a bare boolean — every verdict decomposes into checks[], each with a stable machine code, a human-readable reason, and the ledger basis it was decided on:

{
  "primitive": "viql.vehicle.eligibility",
  "schema": "vehicle-eligibility/v1",
  "eligible": false,
  "reasons": ["not_permitted_at_airport"],
  "vehicle": { "name": "2026 Toyota Sequoia Platinum", "vin": "7SVAAABA8TX085006",
               "seats": 7, "type": "vehicle", "operated_by": "Volt and Velvet Mobility LLC" },
  "trip": { "airport": "SFO", "passengers": 4, "trip_date": "2026-07-21", "same_day": true },
  "checks": [
    { "dimension": "airport_permit", "status": "fail", "code": "not_permitted_at_airport",
      "reason": "no airport permit on the ledger for SFO",
      "basis": [{ "source": "ENTITIES.md § vvm", "finding": "no airport_permit entry with airport=SFO" }] },
    { "dimension": "insurance", "status": "pass", "code": "ok", "...": "..." }
  ],
  "provenance": { "ledger": "ENTITIES.md § vvm", "ledger_sha256": "…64 hex…",
                  "read_model": "build-time snapshot, drift-gated in CI" }
}

• Check statuses are pass | fail | unknown | not_evaluated — the endpoint says which, it does not guess.
• Stable failure codes (not_permitted_at_airport, insufficient_capacity, asset_unavailable, insurance_not_in_force, permit_expired, …) are actionable: an agent can retry OAK instead of SFO, split the party, or pick another date.
• provenance.ledger_sha256 pins the exact compliance-ledger state that produced the verdict.

What this endpoint cannot do

Related surfaces

A free sibling route exists for named, allowlisted partners; this paid route is the only open admission path. A booking-intent endpoint exists but is allowlisted and stops at reviewable intent — it cannot reach "booked."