{ "openapi": "3.1.0", "info": { "title": "tryx402 Gateway API", "version": "1.0.0", "description": "tryx402 — Developer documentation, API reference, OpenAPI 3.1 specification, OAuth 2.0 auth, and MCP server for autonomous AI agents paying over the x402 protocol." }, "servers": [ { "url": "https://www.tryx402.app", "description": "tryx402 Production Gateway Interface" } ], "security": [ { "apiKeyAuth": [] }, { "oauth2": ["tools.read", "tools.execute"] } ], "paths": { "/docs": { "get": { "summary": "tryx402 Developer Documentation Index", "description": "Complete documentation index for tryx402 spend governance, MCP configuration, and x402 payment routing.", "operationId": "getDocumentationIndex", "responses": { "200": { "description": "Developer documentation in Markdown format", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentationContent" } }, "text/markdown": { "schema": { "$ref": "#/components/schemas/DocumentationContent" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/pricing": { "get": { "summary": "Machine-readable fee schedule & pricing rules for tryx402", "description": "Returns the complete machine-readable fee schedule, zero-fee discovery tools, and fiat billing options.", "operationId": "getPricingCatalog", "responses": { "200": { "description": "Pricing rules and supported settlement currencies", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests allowed per minute", "schema": { "type": "integer", "example": 120 } }, "X-RateLimit-Remaining": { "description": "The number of allowed requests remaining in the current period", "schema": { "type": "integer", "example": 119 } }, "X-RateLimit-Reset": { "description": "Unix timestamp when the rate limit window resets", "schema": { "type": "integer", "example": 1787424000 } }, "RateLimit-Limit": { "description": "IETF RateLimit limit per minute", "schema": { "type": "integer", "example": 120 } }, "RateLimit-Remaining": { "description": "IETF RateLimit remaining requests", "schema": { "type": "integer", "example": 119 } }, "RateLimit-Reset": { "description": "IETF RateLimit reset window in seconds", "schema": { "type": "integer", "example": 60 } }, "Sunset": { "description": "RFC 8594 Sunset date for version deprecation", "schema": { "type": "string", "example": "Wed, 01 Sep 2027 00:00:00 GMT" } }, "Link": { "description": "Deprecation policy link relation", "schema": { "type": "string", "example": "; rel=\"deprecation\"" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingCatalog" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/call": { "post": { "summary": "Execute a budget-capped x402 call with tryx402 governance", "description": "Executes a paid HTTP request through the tryx402 gateway with pre-authorized budget check, idempotency protection, and per-call ledger tracking.", "operationId": "executeGatewayCall", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique UUID key to ensure exactly-once execution and prevent duplicate charges on retries", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "description": "Target endpoint URL and budget parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayCallRequest" } } } }, "responses": { "200": { "description": "Successful execution with cost ledger record", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" } }, "Sunset": { "schema": { "type": "string" } }, "Link": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayCallResponse" } } } }, "402": { "description": "Payment required handshake returned by upstream provider", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredError" } } } }, "422": { "description": "BudgetExceeded: call blocked by local policy before payment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } } }, "components": { "schemas": { "DocumentationContent": { "type": "object", "required": ["title", "overview", "links"], "properties": { "title": { "type": "string", "example": "tryx402 — Developer Documentation" }, "overview": { "type": "string", "example": "The budget router and execution gateway for AI agents consuming paid x402 APIs." }, "links": { "type": "object", "properties": { "full_guide": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "pricing": { "type": "string", "format": "uri" }, "mcp_server": { "type": "string", "format": "uri" } } } } }, "GatewayCallRequest": { "type": "object", "required": ["url"], "properties": { "url": { "type": "string", "format": "uri", "description": "Target HTTP 402 API endpoint URL" }, "method": { "type": "string", "enum": ["GET", "POST", "PUT", "DELETE"], "default": "POST", "description": "HTTP method to invoke" }, "body": { "type": "object", "description": "JSON request body payload to forward to the target API" }, "price": { "type": "number", "description": "Expected price in USD for pre-authorization budget verification" }, "max_budget": { "type": "number", "description": "Hard budget ceiling for this call in USD" } } }, "GatewayCallResponse": { "type": "object", "required": ["status", "spent_usd", "data", "receipt"], "properties": { "status": { "type": "string", "example": "ok", "description": "Execution status indicator" }, "spent_usd": { "type": "number", "example": 0.04, "description": "Actual USD amount debited and recorded in the cost ledger" }, "data": { "type": "object", "description": "Raw response data returned by the upstream API provider" }, "receipt": { "type": "string", "example": "rec_0x123abc456", "description": "Cryptographic execution proof and ledger tracking receipt" } } }, "PricingCatalog": { "type": "object", "description": "Fee schedule, pricing rules, and supported settlement currencies for tryx402", "required": ["version", "currency", "settlement", "fiat_billing", "gateway_fees"], "properties": { "version": { "type": "string", "example": "1.0.0" }, "currency": { "type": "string", "example": "USD" }, "settlement": { "type": "object", "required": ["protocol", "primary_asset", "supported_chains", "minimum_ticket_usd"], "properties": { "protocol": { "type": "string", "example": "x402" }, "primary_asset": { "type": "string", "example": "USDC" }, "supported_chains": { "type": "array", "items": { "type": "string" }, "example": ["Base", "Solana"] }, "minimum_ticket_usd": { "type": "number", "example": 0.001 } } }, "fiat_billing": { "type": "object", "required": ["supported_currencies", "funding_method", "accounting_precision"], "properties": { "supported_currencies": { "type": "array", "items": { "type": "string" }, "example": ["EUR", "USD", "GBP", "JPY"] }, "funding_method": { "type": "string", "example": "Stripe Checkout" }, "accounting_precision": { "type": "string", "example": "integer minor units" } } }, "gateway_fees": { "type": "object", "required": ["search", "discover", "budget_enforcement", "call_routing"], "properties": { "search": { "type": "object", "properties": { "price_usd": { "type": "number", "example": 0.0 }, "type": { "type": "string", "example": "free" } } }, "discover": { "type": "object", "properties": { "price_usd": { "type": "number", "example": 0.0 }, "type": { "type": "string", "example": "free" } } }, "budget_enforcement": { "type": "object", "properties": { "price_usd": { "type": "number", "example": 0.0 }, "type": { "type": "string", "example": "free" } } }, "call_routing": { "type": "object", "properties": { "price_usd": { "type": "number", "example": 0.0 }, "type": { "type": "string", "example": "pass-through" } } } } } } }, "PaymentRequiredError": { "type": "object", "description": "HTTP 402 Payment Required response challenge returned by upstream x402 endpoints", "required": ["error", "protocol", "currency", "network", "amount", "recipient"], "properties": { "error": { "type": "string", "example": "Payment Required" }, "protocol": { "type": "string", "example": "x402" }, "currency": { "type": "string", "example": "USDC" }, "network": { "type": "string", "example": "base" }, "amount": { "type": "number", "example": 0.01 }, "recipient": { "type": "string", "example": "0xEc81A3aa7e9d06981395dEf6999b30dCBa726Ca6" }, "description": { "type": "string" } } }, "ApiError": { "type": "object", "description": "Standard structured API error response", "required": ["code", "message"], "properties": { "code": { "type": "string", "example": "BUDGET_EXCEEDED" }, "message": { "type": "string", "example": "Session budget ceiling exceeded before signature dispatch." }, "resolution": { "type": "string", "example": "Increase session budget or obtain operator approval." } } } }, "securitySchemes": { "oauth2": { "type": "oauth2", "description": "OAuth 2.0 authorization for AI agents per RFC 8414 and WorkOS auth.md", "flows": { "clientCredentials": { "tokenUrl": "https://www.tryx402.app/oauth2/token", "scopes": { "tools.read": "Discover available x402 tools and pricing", "tools.execute": "Execute budget-capped x402 paid tool-calls", "billing.read": "Read session spend metrics and cost ledgers" } } } }, "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Direct API key / Bearer token authentication" } } } }