{
  "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 and track automated asynchronous delivery.",
    "version": "1.0.0",
    "contact": {
      "email": "info@curioinvest.com"
    },
    "x-guidance": "Use POST /purchases/xauh/requests/x402 with JSON input to receive an x402 Payment Required challenge, then retry with PAYMENT-SIGNATURE after paying. A successful retry confirms payment and starts automated XAUH delivery asynchronously; poll statusUrl until COMPLETED, when tonTransferTxHash is exposed if available. Empty GET or POST probes return discovery-only 402 metadata."
  },
  "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. An empty body may be used for discovery probes; real purchases require a TON wallet from JWT or tonWalletAddress and exactly one of paymentAmount or xauhAmount. Retry with PAYMENT-SIGNATURE after payment verification and settlement. A successful retry confirms payment and starts automated XAUH delivery asynchronously; the response may initially report PAYMENT_RECEIVED and DELIVERY_PENDING. Poll statusUrl until COMPLETED, when tonTransferTxHash is exposed if available.",
        "parameters": [],
        "requestBody": {
          "required": false,
          "description": "Optional for discovery probes. Required for real purchases unless the request only needs the x402 discovery challenge.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateXauhX402PurchaseRequestDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "x402 payment settled and XAUH purchase request created; automated XAUH delivery may still be pending",
            "headers": {
              "PAYMENT-RESPONSE": {
                "description": "Base64-encoded x402 settlement response",
                "schema": {
                  "type": "string"
                }
              },
              "EXTENSION-RESPONSES": {
                "description": "Facilitator extension responses, when returned by the x402 facilitator",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/XauhX402PurchaseResponseDto"
                }
              }
            }
          },
          "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"
                }
              },
              "EXTENSION-RESPONSES": {
                "description": "Facilitator extension responses, when returned by the x402 facilitator",
                "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": []
          },
          {}
        ],
        "x-payment-info": {
          "protocols": [
            {
              "x402": {}
            }
          ],
          "price": {
            "mode": "dynamic",
            "currency": "USD",
            "min": "1",
            "max": "1000000"
          }
        }
      }
    },
    "/purchases/xauh/requests/{id}": {
      "get": {
        "operationId": "XauhPurchaseRequestsController_getPurchaseRequestById",
        "summary": "Get XAUH purchase request info by ID",
        "description": "Returns the asynchronous lifecycle state for x402, Changelly, or Wert purchase requests. PENDING covers provider or payment processing; PAYMENT_RECEIVED means payment is confirmed and automated XAUH delivery is pending; COMPLETED confirms delivery and tonTransferTxHash is exposed when available. Poll this endpoint until a terminal status.",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Current purchase and automated XAUH delivery status",
            "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"
                    }
                  }
                }
              }
            }
          },
          "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:8453"
          },
          "paymentAsset": {
            "type": "string",
            "description": "Supported x402 payment asset symbol for the active x402 network. Defaults to USDC.",
            "example": "USDC"
          },
          "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"
          }
        }
      },
      "XauhX402PurchaseResponseDto": {
        "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",
            "example": "0:e02892e29a92ebbb3d9172eb12cf5d15a35bb1d2045648e0933fd738af3b4a9a"
          },
          "statusUrl": {
            "type": "string",
            "description": "Canonical purchase request status URL to poll for automated delivery progress until a terminal status",
            "example": "/v1/purchases/xauh/requests/6f75f827-b950-48bd-8cf7-666f89ebc4e7"
          },
          "xauhAmount": {
            "type": "string",
            "description": "Human-readable XAUH amount",
            "example": "0.0074095149930618"
          },
          "xauhAmountAtomic": {
            "type": "string",
            "description": "XAUH amount in atomic units",
            "example": "7409514993061800"
          },
          "xauhDecimals": {
            "type": "number",
            "description": "XAUH token decimals",
            "example": 18
          },
          "status": {
            "type": "string",
            "description": "Purchase lifecycle status. PAYMENT_RECEIVED means payment is confirmed and automated XAUH delivery is pending; COMPLETED confirms delivery.",
            "enum": ["PENDING", "PAYMENT_RECEIVED", "COMPLETED", "FAILED", "CANCELLED"]
          },
          "deliveryStatus": {
            "type": "string",
            "description": "XAUH delivery status. DELIVERY_PENDING means automated delivery is still running; COMPLETED confirms delivery.",
            "enum": ["DELIVERY_PENDING", "COMPLETED", "FAILED", "CANCELLED"]
          },
          "payment": {
            "description": "x402 payment details",
            "allOf": [
              {
                "$ref": "#/components/schemas/XauhX402PaymentDto"
              }
            ]
          },
          "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
          },
          "tonTransferTxHash": {
            "type": "string",
            "description": "TON transfer transaction hash, exposed when delivery is completed and the hash is available",
            "nullable": true
          },
          "createdAt": {
            "format": "date-time",
            "type": "string",
            "description": "Creation time"
          }
        },
        "required": [
          "id",
          "userId",
          "tonWalletAddress",
          "statusUrl",
          "xauhAmount",
          "xauhAmountAtomic",
          "xauhDecimals",
          "status",
          "deliveryStatus",
          "payment",
          "paymentReceivedAt",
          "failedAt",
          "completedAt",
          "tonTransferTxHash",
          "createdAt"
        ]
      },
      "XauhX402PaymentRequiredDto": {
        "type": "object",
        "properties": {
          "x402Version": {
            "type": "number",
            "description": "x402 protocol version",
            "example": 2
          },
          "error": {
            "type": "string",
            "description": "Payment challenge error"
          },
          "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", "expiresAt", "tonWalletAddress", "resource", "accepts"]
      },
      "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 lifecycle status. PAYMENT_RECEIVED means payment is confirmed and automated XAUH delivery is pending; COMPLETED confirms delivery.",
            "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, exposed when delivery is completed and the hash is available",
            "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"
        ]
      },
      "XauhX402PaymentDto": {
        "type": "object",
        "properties": {
          "assetSymbol": {
            "type": "string",
            "description": "Payment asset ticker",
            "example": "USDC"
          },
          "assetAddress": {
            "type": "string",
            "description": "Payment asset contract or token identifier",
            "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
          },
          "network": {
            "type": "string",
            "description": "x402 CAIP-2 payment network identifier",
            "example": "eip155:8453"
          },
          "amount": {
            "type": "string",
            "description": "Human-readable payment amount",
            "example": "1"
          },
          "amountAtomic": {
            "type": "string",
            "description": "Payment amount in atomic units",
            "example": "1000000"
          },
          "decimals": {
            "type": "number",
            "description": "Payment asset decimals",
            "example": 6
          },
          "txHash": {
            "type": "string",
            "description": "Payment settlement transaction hash",
            "example": "0xf409875ceb8f5003b27ae7bf169b0497cf80c23c9b866a79f6cfcc17782768ce"
          },
          "explorerUrl": {
            "type": "string",
            "description": "Payment settlement transaction explorer URL",
            "nullable": true,
            "example": "https://basescan.org/tx/0xf409875ceb8f5003b27ae7bf169b0497cf80c23c9b866a79f6cfcc17782768ce"
          }
        },
        "required": [
          "assetSymbol",
          "assetAddress",
          "network",
          "amount",
          "amountAtomic",
          "decimals",
          "txHash",
          "explorerUrl"
        ]
      },
      "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"
          },
          "serviceName": {
            "type": "string",
            "description": "Paid resource service name",
            "example": "Herculis Gold Coin"
          },
          "tags": {
            "description": "Paid resource discovery tags",
            "example": ["herculis", "xauh", "gold", "rwa", "ton"],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "iconUrl": {
            "type": "string",
            "description": "Paid resource icon URL"
          }
        },
        "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"]
      },
      "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, synchronized automatically for supported provider flows",
            "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",
              "RECEIVING_ADDRESS_MISMATCH",
              "UNVERIFIED_SMART_CONTRACT_CALL",
              "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": "Provider rate ID, when the provider exposes one",
            "nullable": true
          },
          "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"
        ]
      }
    },
    "securitySchemes": {
      "bearer": {
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "type": "http"
      }
    }
  }
}