{ "openapi": "3.0.0", "info": { "title": "JAMTON XAUH x402 Purchase API", "description": "Dedicated OpenAPI surface for agents and wallets that purchase XAUH through the x402 payment flow.", "version": "1.0.0" }, "servers": [ { "url": "https://api.jamton.network/v1", "description": "Production" } ], "tags": [ { "name": "purchases/xauh", "description": "Public XAUH purchase endpoints" } ], "paths": { "/purchases/xauh/requests/x402": { "post": { "operationId": "XauhPurchaseRequestsController_createX402PurchaseRequest", "summary": "Create XAUH purchase request with x402 payment (JWT is optional)", "description": "Returns HTTP 402 with PAYMENT-REQUIRED when unpaid. Retry with PAYMENT-SIGNATURE after payment verification and settlement.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateXauhX402PurchaseRequestDto" } } } }, "responses": { "200": { "description": "x402 payment settled and XAUH purchase request created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XauhPurchaseRequestDto" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 400 }, "message": { "type": "array", "items": { "type": "string", "example": "address must be an Ethereum address" } }, "error": { "type": "string", "example": "Bad Request" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 401 }, "message": { "type": "string", "example": "Unauthorized access" }, "error": { "type": "string", "example": "Unauthorized" } } } } } }, "402": { "description": "x402 payment required or verification/settlement failed", "headers": { "PAYMENT-REQUIRED": { "description": "Base64-encoded x402 PaymentRequired payload", "schema": { "type": "string" } }, "PAYMENT-RESPONSE": { "description": "Base64-encoded x402 settlement response when settlement was attempted", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XauhX402PaymentRequiredDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 403 }, "message": { "type": "string", "example": "Forbidden resource" }, "error": { "type": "string", "example": "Forbidden" } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 429 }, "message": { "type": "string", "example": "ThrottlerException: Too Many Requests" } } } } } } }, "tags": ["purchases/xauh"], "security": [ { "bearer": [] }, {} ] } }, "/purchases/xauh/requests/{id}": { "get": { "operationId": "XauhPurchaseRequestsController_getPurchaseRequestById", "summary": "Get XAUH purchase request info by ID", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XauhPurchaseRequestDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 404 }, "message": { "type": "string", "example": "Not Found" } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 429 }, "message": { "type": "string", "example": "ThrottlerException: Too Many Requests" } } } } } } }, "tags": ["purchases/xauh"] } } }, "components": { "schemas": { "CreateXauhX402PurchaseRequestDto": { "type": "object", "properties": { "tonWalletAddress": { "type": "string", "description": "Optional TON wallet address to receive purchased XAUH. If provided, it overrides JWT user resolution.", "nullable": true, "example": "0:575bedd5aa515d3b87548d933b3011c1cc462994ff5efdec2ba88ca0d233fd65" }, "network": { "type": "string", "description": "x402 CAIP-2 network identifier", "default": "eip155:8453", "example": "eip155:84532" }, "paymentAsset": { "type": "string", "description": "Supported x402 payment asset symbol. Defaults to USDT on Base mainnet and Base Sepolia.", "example": "USDT" }, "paymentAmount": { "type": "string", "description": "Payment amount in the configured payment asset. Exactly one of paymentAmount or xauhAmount is required.", "example": "125.45" }, "xauhAmount": { "type": "string", "description": "Target XAUH amount. Exactly one of paymentAmount or xauhAmount is required.", "example": "0.12345" } } }, "XauhPurchaseRequestDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Purchase request ID", "format": "uuid" }, "userId": { "type": "string", "description": "User ID", "format": "uuid" }, "tonWalletAddress": { "type": "string", "description": "TON wallet address that will receive XAUH jettons" }, "xauhAmount": { "type": "string", "description": "XAUH amount in atomic units (18 decimals)", "example": "123450000000000000" }, "xauhAmountDisplay": { "type": "string", "description": "Human-readable XAUH amount", "example": "0.12345" }, "status": { "type": "string", "description": "Purchase status", "enum": ["PENDING", "PAYMENT_RECEIVED", "COMPLETED", "FAILED", "CANCELLED"] }, "failureReason": { "type": "string", "description": "Purchase failure reason", "enum": ["PAYMENT_FAILED", "TON_TRANSFER_FAILED", "INTERNAL_ERROR", "OTHER"], "nullable": true }, "cancellationReason": { "type": "string", "description": "Purchase cancellation reason", "enum": ["PAYMENT_ORDER_CANCELLED", "USER_REQUEST", "OTHER"], "nullable": true }, "paymentReceivedAt": { "format": "date-time", "type": "string", "description": "Payment received timestamp", "nullable": true }, "failedAt": { "format": "date-time", "type": "string", "description": "Failure timestamp", "nullable": true }, "completedAt": { "format": "date-time", "type": "string", "description": "Completion timestamp", "nullable": true }, "cancelledAt": { "format": "date-time", "type": "string", "description": "Cancellation timestamp", "nullable": true }, "tonTransferTxHash": { "type": "string", "description": "TON transfer transaction hash", "nullable": true }, "xauUsdPriceRaw": { "type": "string", "description": "XAU/USD price from Chainlink (raw answer)" }, "xauUsdPriceGramRaw": { "type": "string", "description": "XAU/USD price for 1 gram of gold (calculated from raw answer)" }, "xauUsdPriceDecimals": { "type": "number", "description": "XAU/USD price decimals" }, "createdAt": { "format": "date-time", "type": "string", "description": "Creation time" }, "paymentOrder": { "description": "Linked payment order", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/XauhPaymentOrderInfoDto" } ] } }, "required": [ "id", "userId", "tonWalletAddress", "xauhAmount", "xauhAmountDisplay", "status", "failureReason", "cancellationReason", "paymentReceivedAt", "failedAt", "completedAt", "cancelledAt", "tonTransferTxHash", "xauUsdPriceRaw", "xauUsdPriceGramRaw", "xauUsdPriceDecimals", "createdAt", "paymentOrder" ] }, "XauhX402PaymentRequiredDto": { "type": "object", "properties": { "x402Version": { "type": "number", "description": "x402 protocol version", "example": 2 }, "error": { "type": "string", "description": "Payment challenge error" }, "quoteId": { "type": "string", "description": "Quote ID", "format": "uuid" }, "expiresAt": { "format": "date-time", "type": "string", "description": "Quote expiration timestamp" }, "tonWalletAddress": { "type": "string", "description": "TON wallet address that will receive purchased XAUH jettons", "example": "0:575bedd5aa515d3b87548d933b3011c1cc462994ff5efdec2ba88ca0d233fd65" }, "resource": { "description": "Paid resource", "allOf": [ { "$ref": "#/components/schemas/XauhX402ResourceDto" } ] }, "accepts": { "description": "Accepted payment requirements", "type": "array", "items": { "$ref": "#/components/schemas/XauhX402PaymentRequirementsDto" } }, "extensions": { "type": "object", "description": "Application metadata included in the x402 PaymentRequired payload" } }, "required": [ "x402Version", "quoteId", "expiresAt", "tonWalletAddress", "resource", "accepts" ] }, "XauhPaymentOrderInfoDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Payment order ID", "format": "uuid" }, "provider": { "type": "string", "description": "Provider type", "enum": ["CHANGELLY", "WERT", "X402"] }, "providerOrderId": { "type": "string", "description": "Provider-side order ID" }, "providerStatusRaw": { "type": "string", "description": "Raw provider status", "nullable": true }, "status": { "type": "string", "description": "Internal payment order status", "enum": ["PENDING", "AML_HOLD", "COMPLETED", "FAILED", "CANCELLED"] }, "failureReason": { "type": "string", "description": "Order failure reason", "enum": [ "PROVIDER_FAILED", "PROVIDER_REFUNDED", "ORDER_EXPIRED", "ORDER_OVERDUE", "AML_REJECTED", "PROVIDER_ERROR", "OTHER" ], "nullable": true }, "cancellationReason": { "type": "string", "description": "Order cancellation reason", "enum": ["PROVIDER_EVENT", "OTHER"], "nullable": true }, "inputCurrency": { "type": "string", "description": "Input currency ticker", "example": "eth" }, "inputAmount": { "type": "string", "description": "Input amount in atomic units", "example": "250000000000000000" }, "inputDecimals": { "type": "number", "description": "Input currency decimals", "example": 18 }, "outputCurrency": { "type": "string", "description": "Output currency ticker", "example": "usdt20" }, "outputAmountExpected": { "type": "string", "description": "Expected output amount before network fee in atomic units", "example": "510245000" }, "outputAmountNet": { "type": "string", "description": "Expected output amount net of network fee in atomic units", "example": "510145000" }, "outputDecimals": { "type": "number", "description": "Output currency decimals", "example": 6 }, "networkFee": { "type": "string", "description": "Network fee in output currency atomic units", "example": "100000" }, "rateId": { "type": "string", "description": "Changelly fixed-rate ID" }, "payinAddress": { "type": "string", "description": "Payin address to show to user" }, "payinExtraId": { "type": "string", "description": "Optional payin extra ID", "nullable": true }, "payTill": { "format": "date-time", "type": "string", "description": "Payin expiration timestamp", "nullable": true }, "trackUrl": { "type": "string", "description": "Provider tracking URL", "nullable": true }, "createdAt": { "format": "date-time", "type": "string", "description": "Order creation time" } }, "required": [ "id", "provider", "providerOrderId", "providerStatusRaw", "status", "failureReason", "cancellationReason", "inputCurrency", "inputAmount", "inputDecimals", "outputCurrency", "outputAmountExpected", "outputAmountNet", "outputDecimals", "networkFee", "rateId", "payinAddress", "payinExtraId", "payTill", "trackUrl", "createdAt" ] }, "XauhX402ResourceDto": { "type": "object", "properties": { "url": { "type": "string", "description": "Paid resource URL", "example": "https://api.jamton.network/v1/purchases/xauh/requests/x402" }, "description": { "type": "string", "description": "Paid resource description" }, "mimeType": { "type": "string", "description": "Paid resource MIME type", "example": "application/json" } }, "required": ["url"] }, "XauhX402PaymentRequirementsDto": { "type": "object", "properties": { "scheme": { "type": "string", "description": "x402 payment scheme", "example": "exact" }, "network": { "type": "string", "description": "CAIP-2 network identifier", "example": "eip155:8453" }, "asset": { "type": "string", "description": "Payment asset contract or token identifier" }, "amount": { "type": "string", "description": "Required amount in atomic token units", "example": "125450000" }, "payTo": { "type": "string", "description": "Merchant receiving address" }, "maxTimeoutSeconds": { "type": "number", "description": "Maximum payment timeout in seconds", "example": 300 }, "extra": { "type": "object", "description": "Scheme-specific metadata" } }, "required": ["scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds", "extra"] } }, "securitySchemes": { "bearer": { "scheme": "bearer", "bearerFormat": "JWT", "type": "http" } } } }