{ "openapi": "3.1.0", "info": { "title": "VYTREL Machine-Payable API", "version": "1.5.2", "description": "Machine-payable public URL observations, Base wallet reads, deterministic hashing, and fresh crypto spot market state. Successful delivery is followed by x402 settlement; failed delivery is not represented as a successful result.", "x-guidance": "Choose the paid route matching the task. Unpaid requests return HTTP 402 with x402 v2 payment requirements; pay the quoted Base USDC amount and retry to receive the result in the same response.", "contact": { "email": "alfendy@wyntrio.com" } }, "servers": [ { "url": "https://vytrel-control.vercel.app" } ], "paths": { "/api/url-proof": { "get": { "operationId": "verifyPublicHttpsUrl", "summary": "Observe a public HTTPS URL from VYTREL", "description": "Returns upstream HTTP status, redirects, latency and SHA-256 of at most 64 KiB. A non-2xx upstream status is a completed observation (ok=true, upstreamOk=false). DNS, TLS, timeout and interrupted-response failures return 502 and are not settled. HTTPS port 443 only. No content body returned. Not a signed attestation.", "tags": [ "Utility", "Proof", "x402" ], "security": [], "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string", "format": "uri", "example": "https://example.com" }, "description": "Public HTTPS URL to verify", "example": "https://example.com" } ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.001" }, "protocols": [ { "x402": {} } ] }, "responses": { "200": { "description": "Live URL verification result", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "requestedUrl": { "type": "string" }, "finalUrl": { "type": "string" }, "status": { "type": "number" }, "contentType": { "type": [ "string", "null" ] }, "bytesSampled": { "type": "number" }, "latencyMs": { "type": "number" }, "checkedAt": { "type": "string", "format": "date-time" }, "sampleSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "upstreamOk": { "type": "boolean" }, "sampleTruncated": { "type": "boolean" }, "sampleLimitBytes": { "type": "integer", "const": 65536 }, "scope": { "type": "string" }, "redirects": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "status": { "type": "integer" } } } } }, "required": [ "ok", "requestedUrl", "finalUrl", "status", "contentType", "bytesSampled", "latencyMs", "checkedAt", "sampleSha256", "upstreamOk", "sampleTruncated", "sampleLimitBytes", "scope", "redirects" ] } } }, "headers": { "PAYMENT-RESPONSE": { "description": "Base64 x402 facilitator settlement receipt; check success, transaction, payer and network", "schema": { "type": "string" } }, "X-VYTREL-Result-SHA256": { "description": "SHA-256 of the exact UTF-8 response body; not a signature", "schema": { "type": "string" } }, "X-VYTREL-Receipt-ID": { "description": "Correlation ID for support; not a publicly retrievable receipt", "schema": { "type": "string", "format": "uuid" } } } }, "400": { "description": "Invalid input; no payment offered or settled" }, "402": { "description": "Payment Required" }, "502": { "description": "Delivery failed; no payment settled" }, "503": { "description": "Payment service unavailable" } } } }, "/api/base-usdc-balance": { "get": { "operationId": "getBaseUsdcBalance", "summary": "Get exact Base USDC wallet balance", "description": "Paid deterministic Base-mainnet USDC balance lookup with block-number provenance.", "tags": [ "Utility", "Crypto", "x402" ], "security": [], "parameters": [ { "name": "address", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "example": "0x0000000000000000000000000000000000000000" }, "description": "EVM wallet address", "example": "0x0000000000000000000000000000000000000000" } ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.001" }, "protocols": [ { "x402": {} } ] }, "responses": { "200": { "description": "USDC balance with block provenance", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 x402 facilitator settlement receipt; check success, transaction, payer and network", "schema": { "type": "string" } }, "X-VYTREL-Result-SHA256": { "description": "SHA-256 of the exact UTF-8 response body; not a signature", "schema": { "type": "string" } }, "X-VYTREL-Receipt-ID": { "description": "Correlation ID for support; not a publicly retrievable receipt", "schema": { "type": "string", "format": "uuid" } } } }, "400": { "description": "Invalid input; no payment offered or settled" }, "402": { "description": "Payment Required" }, "502": { "description": "Delivery failed; no payment settled" }, "503": { "description": "Payment service unavailable" } } } }, "/api/sha256": { "get": { "operationId": "sha256Text", "summary": "SHA-256 UTF-8 text", "description": "Deterministic SHA-256 digest for UTF-8 text up to 64 KiB.", "tags": [ "Utility", "x402" ], "security": [], "parameters": [ { "name": "text", "in": "query", "required": true, "schema": { "type": "string", "example": "hello" }, "description": "UTF-8 text to hash", "example": "hello" } ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.001" }, "protocols": [ { "x402": {} } ] }, "responses": { "200": { "description": "SHA-256 digest", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 x402 facilitator settlement receipt; check success, transaction, payer and network", "schema": { "type": "string" } }, "X-VYTREL-Result-SHA256": { "description": "SHA-256 of the exact UTF-8 response body; not a signature", "schema": { "type": "string" } }, "X-VYTREL-Receipt-ID": { "description": "Correlation ID for support; not a publicly retrievable receipt", "schema": { "type": "string", "format": "uuid" } } } }, "400": { "description": "Invalid input; no payment offered or settled" }, "402": { "description": "Payment Required" }, "502": { "description": "Delivery failed; no payment settled" }, "503": { "description": "Payment service unavailable" } } } }, "/api/base-wallet-snapshot": { "get": { "operationId": "getBaseWalletSnapshot", "summary": "Get Base ETH + USDC wallet snapshot", "description": "Paid Base-mainnet wallet snapshot returning native ETH and USDC ERC-20 balances at one pinned block with block-number provenance and timestamp.", "tags": [ "Utility", "Crypto", "Portfolio", "x402" ], "security": [], "parameters": [ { "name": "address", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "example": "0x0000000000000000000000000000000000000000" }, "description": "EVM wallet address", "example": "0x0000000000000000000000000000000000000000" } ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.005" }, "protocols": [ { "x402": {} } ] }, "responses": { "200": { "description": "Base wallet snapshot with ETH and USDC balances at one pinned block", "headers": { "PAYMENT-RESPONSE": { "description": "Base64 x402 facilitator settlement receipt; check success, transaction, payer and network", "schema": { "type": "string" } }, "X-VYTREL-Result-SHA256": { "description": "SHA-256 of the exact UTF-8 response body; not a signature", "schema": { "type": "string" } }, "X-VYTREL-Receipt-ID": { "description": "Correlation ID for support; not a publicly retrievable receipt", "schema": { "type": "string", "format": "uuid" } } } }, "400": { "description": "Invalid input; no payment offered or settled" }, "402": { "description": "Payment Required" }, "502": { "description": "Delivery failed; no payment settled" }, "503": { "description": "Payment service unavailable" } } } }, "/api/market-state": { "get": { "operationId": "getMarketState", "summary": "Get fresh BTC, ETH or SOL spot market state", "description": "Paid machine-ready spot market observation composed from live Coinbase Exchange public REST data. Returns price, bid/ask spread, 24h range/change, volume, mechanical direction/regime, freshness and provenance. Mechanical observation only; not a trading recommendation.", "tags": [ "Market Data", "Crypto", "x402" ], "security": [], "parameters": [ { "name": "symbol", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "BTCUSDT", "ETHUSDT", "SOLUSDT" ], "example": "BTCUSDT" }, "description": "Supported canonical market symbol" } ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.005" }, "protocols": [ { "x402": {} } ] }, "responses": { "200": { "description": "Fresh machine-readable market state with provenance" }, "400": { "description": "Unsupported symbol; no payment offered" }, "402": { "description": "Payment Required" }, "502": { "description": "Live upstream fulfillment failed" }, "503": { "description": "Payment service unavailable" } } } }, "/api/crypto-price": { "get": { "operationId": "getCryptoPrice", "summary": "Get live BTC, ETH or SOL price", "description": "Low-friction machine price quote from Coinbase Exchange public ticker data. Returns USD price, bid, ask, spread, timestamp and source. Keyless x402 on Base USDC.", "tags": [ "Market Data", "Crypto", "Price", "x402" ], "security": [], "parameters": [ { "name": "symbol", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "BTC", "ETH", "SOL" ], "example": "BTC" }, "description": "Crypto asset symbol" } ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.001" }, "protocols": [ { "x402": {} } ] }, "responses": { "200": { "description": "Fresh price quote" }, "400": { "description": "Unsupported symbol" }, "402": { "description": "Payment Required" }, "502": { "description": "Upstream fulfillment failed" }, "503": { "description": "Payment service unavailable" } } } }, "/api/verify-domain": { "get": { "operationId": "verifyDomainDns", "summary": "Get domain A and MX DNS evidence", "description": "Live DNS evidence via fixed public DoH resolvers. Explicit null MX and NXDOMAIN results. DNS_A_MX_ONLY; NOT_EMAIL_VALIDATION. No SMTP, mailbox validation or guaranteed deliverability. DNS provider failure returns 502.", "tags": [ "Domain Verification", "DNS", "x402" ], "security": [], "parameters": [ { "name": "domain", "in": "query", "required": true, "schema": { "type": "string", "example": "example.com" }, "example": "example.com", "description": "DNS domain only, not a URL, email or IP" } ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002" }, "protocols": [ { "x402": {} } ] }, "responses": { "200": { "description": "Completed DNS observation, including negative records", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "schema": { "type": "string" }, "domain": { "type": "string" }, "a_confirmed": { "type": "boolean" }, "a_addresses": { "type": "array", "items": { "type": "string" } }, "mx_confirmed": { "type": "boolean" }, "mx_hosts": { "type": "array", "items": { "type": "string" } }, "mx_records": { "type": "array", "items": { "type": "object", "properties": { "priority": { "type": "integer" }, "host": { "type": "string" } }, "required": [ "priority", "host" ] } }, "null_mx": { "type": "boolean" }, "dns_status": { "type": "string", "enum": [ "NOERROR", "NXDOMAIN" ] }, "smtp_checked": { "type": "boolean", "const": false }, "mailbox_deliverability": { "type": "string", "const": "NOT_TESTED" }, "proof_scope": { "type": "string" }, "observed_at": { "type": "string", "format": "date-time" }, "resolver": { "type": "string" }, "evidence": { "type": "array", "items": { "type": "object" } } }, "required": [ "ok", "schema", "domain", "a_confirmed", "a_addresses", "mx_confirmed", "mx_hosts", "mx_records", "null_mx", "dns_status", "smtp_checked", "mailbox_deliverability", "proof_scope", "observed_at", "resolver", "evidence" ] }, "example": { "ok": true, "schema": "vytrel.domain-evidence.v1", "domain": "example.com", "a_confirmed": true, "a_addresses": [ "93.184.216.34" ], "mx_confirmed": false, "mx_hosts": [], "mx_records": [ { "priority": 0, "host": "." } ], "null_mx": true, "dns_status": "NOERROR", "smtp_checked": false, "mailbox_deliverability": "NOT_TESTED", "proof_scope": "DNS_A_MX_ONLY; NOT_EMAIL_VALIDATION", "observed_at": "2026-10-06T18:00:00.000Z", "resolver": "https://cloudflare-dns.com/dns-query", "evidence": [] } } } }, "400": { "description": "Invalid domain; no quote" }, "402": { "description": "Base USDC payment required" }, "502": { "description": "DNS evidence unavailable; no successful delivery" }, "503": { "description": "Payment service unavailable" } } } }, "/api/verify-domain/batch": { "post": { "operationId": "verifyDomainBatch", "summary": "10\u2013250 unique domains; $0.0015 per domain, $0.015 minimum. All-or-nothing DNS delivery.", "description": "DNS_A_MX_ONLY; NOT_EMAIL_VALIDATION. Authorization verified before execution; settlement after successful delivery. Payment fields alone never authorize artifact retrieval. Settled retries return 409; use the free wallet-authenticated replay path. Unresolved requests require reconciliation, never a second payment. Current production state: GATED_STORAGE_BINDING. Returns 503 without PAYMENT-REQUIRED until canonical job database readiness passes.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domains", "idempotency_key" ], "properties": { "domains": { "type": "array", "minItems": 10, "maxItems": 250, "uniqueItems": true, "items": { "type": "string" } }, "idempotency_key": { "type": "string", "minLength": 16, "maxLength": 128 } } } } } }, "responses": { "200": { "description": "DNS evidence with PAYMENT-RESPONSE confirmed settlement and exact-byte SHA-256 response headers" }, "400": { "description": "Invalid input; no execution" }, "402": { "description": "Standard x402 payment requirement" }, "409": { "description": "Idempotency conflict or unresolved request; do not send a second payment" }, "502": { "description": "Delivery failed; no successful settlement" }, "503": { "description": "Payment/storage unavailable; execution blocked" } }, "x-price-usd": 0.0015, "x-pricing-unit": "domain" } }, "/api/verify-domain/batch/replay": { "post": { "operationId": "replayDomainBatch", "summary": "Retrieve a settled batch with fresh EOA wallet authentication; never charges or executes DNS.", "description": "Send the original batch body plus x-vytrel-replay-payer. Without a signature, 401 returns replay_message and expiry. Sign the exact replay_message using EIP-191 personal_sign with the payer wallet. Repeat with original PAYMENT-SIGNATURE as a lookup selector, x-vytrel-replay-payer, x-vytrel-replay-expiry, x-vytrel-replay-signature. The signature binds origin, original route, request key, canonical input hash, payer, Base chain and expiry (within 5 minutes). Signer must match stored confirmed settlement payer. EOA signatures supported; contract-wallet verification not implemented.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domains", "idempotency_key" ], "properties": { "domains": { "type": "array", "minItems": 10, "maxItems": 250, "uniqueItems": true, "items": { "type": "string" } }, "idempotency_key": { "type": "string", "minLength": 16, "maxLength": 128 } } } } } }, "parameters": [ { "in": "header", "name": "PAYMENT-SIGNATURE", "required": false, "schema": { "type": "string" } }, { "in": "header", "name": "x-vytrel-replay-payer", "required": false, "schema": { "type": "string" } }, { "in": "header", "name": "x-vytrel-replay-expiry", "required": false, "schema": { "type": "string" } }, { "in": "header", "name": "x-vytrel-replay-signature", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Exact stored response bytes and original receipt headers; no settlement or execution" }, "400": { "description": "Invalid original batch or payment selector" }, "401": { "description": "Signature challenge or invalid/expired wallet proof" }, "403": { "description": "Signer does not own settled artifact" }, "409": { "description": "No matching settled artifact" }, "503": { "description": "Storage or receipt reconciliation required" } } } } } }