{"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":"Production payments support Base eip155:8453 with USDC (default), USDT, or USDS, and TON tvm:-239 with USDT. Base remains the default when network is omitted; select network tvm:-239 and paymentAsset USDT for TON. tonWalletAddress is the XAUH delivery recipient, while the signed payment payload determines the payer. Use POST /purchases/xauh/requests/x402 with JSON input to receive an x402 Payment Required challenge, then retry with PAYMENT-SIGNATURE after paying. USDS payments use Permit2 and require a one-time token approval for Permit2 before the payer signs the payment. TON challenges include facilitator-provided relay parameters in accepts[].extra. 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. When MPP is enabled, Base USDC quotes also return WWW-Authenticate: Payment (evm/charge). Sign the challenge and retry the same purchase body using Authorization: Payment, or Payment-Credential when advertised for JWT coexistence. Use exactly one payment protocol per retry. Successful MPP retries return Payment-Receipt and the same purchase/statusUrl contract. Discovery-only challenges cannot be paid; obtain a quote with a full purchase body first."},"x-mcp-server":{"url":"https://api.jamton.network/v1/x402/mcp","transport":"streamable-http","x402Version":2,"paymentRequirements":{"discoveryUrl":"https://api.jamton.network/.well-known/x402","networks":[{"network":"eip155:8453","assets":[{"symbol":"USDC","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","decimals":6,"maxTimeoutSeconds":300},{"symbol":"USDT","asset":"0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2","decimals":6,"maxTimeoutSeconds":300},{"symbol":"USDS","asset":"0x820c137fa70c8691f0e44dc420a5e53c168921dc","decimals":18,"maxTimeoutSeconds":300}]},{"network":"tvm:-239","assets":[{"symbol":"USDT","asset":"0:b113a994b5024a16719f69139328eb759596c38a25f59028b146fecdc3621dfe","decimals":6,"maxTimeoutSeconds":120}]}]},"tools":[{"name":"purchase_xauh","description":"Purchase tokenized physical gold (XAUH) on TON using the x402 payment protocol.","paidResource":"mcp://tool/x402/purchase_xauh","inputSchema":{"type":"object","additionalProperties":false,"properties":{"tonWalletAddress":{"type":"string","description":"TON wallet address that will receive purchased XAUH jettons."},"network":{"type":"string","description":"Optional CAIP-2 x402 payment network. Use list_x402_payment_options to discover supported values."},"paymentAsset":{"type":"string","description":"Optional x402 payment asset symbol. Use list_x402_payment_options to discover supported values."},"paymentAmount":{"type":"string","pattern":"^(?=.{1,64}$)(?=[0-9.]*[1-9])[0-9]{1,18}(?:\\.[0-9]+)?(?![\\s\\S])","maxLength":64,"description":"Payment amount in the configured payment asset. Exactly one of paymentAmount or xauhAmount is required. Positive plain decimal string, greater than 0 and less than 1000000000000000000. At most 64 characters and 18 integer digits (including leading zeros). No signs, whitespace, or exponent notation. Fractional precision must fit the token; trailing fractional zeros are allowed."},"xauhAmount":{"type":"string","pattern":"^(?=.{1,64}$)(?=[0-9.]*[1-9])[0-9]{1,18}(?:\\.[0-9]+)?(?![\\s\\S])","maxLength":64,"description":"Target XAUH amount. Exactly one of paymentAmount or xauhAmount is required. Positive plain decimal string, greater than 0 and less than 1000000000000000000. At most 64 characters and 18 integer digits (including leading zeros). No signs, whitespace, or exponent notation. Fractional precision must fit the token; trailing fractional zeros are allowed."}},"required":["tonWalletAddress"],"oneOf":[{"required":["paymentAmount"],"not":{"required":["xauhAmount"]}},{"required":["xauhAmount"],"not":{"required":["paymentAmount"]}}]}}]},"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":"Buy tokenized physical gold (XAUH) with x402 or MPP payments","description":"Returns HTTP 402 with PAYMENT-REQUIRED when unpaid. Production payments support Base eip155:8453 with USDC (default) or USDT, and TON tvm:-239 with USDT. Base remains the default when network is omitted; TON callers must select tvm:-239. When MPP is enabled, Base USDC also offers WWW-Authenticate: Payment (evm/charge). Retry the same purchase body with exactly one payment protocol: PAYMENT-SIGNATURE for x402, or the credential header advertised by MPP (Authorization or Payment-Credential when using a Bearer JWT). Successful MPP responses include Payment-Receipt. An empty body may be used for discovery probes; those challenges cannot be paid. Real purchases require a TON wallet from JWT or tonWalletAddress and exactly one of paymentAmount or xauhAmount. tonWalletAddress is the XAUH delivery recipient, while the signed payment payload determines the payer. 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":[{"name":"Payment-Credential","in":"header","description":"MPP Payment credential when the challenge advertises this header; permits a separate Bearer JWT. Otherwise send Authorization: Payment. Never combine MPP and x402 credentials.","required":false,"schema":{"type":"string"}}],"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"},"examples":{"baseMainnetUsdc":{"summary":"Pay with USDC on Base mainnet and receive XAUH on TON","value":{"tonWalletAddress":"0:575bedd5aa515d3b87548d933b3011c1cc462994ff5efdec2ba88ca0d233fd65","network":"eip155:8453","paymentAsset":"USDC","paymentAmount":"1000"}},"tonMainnetUsdt":{"summary":"Pay with USDT on TON mainnet and receive XAUH on TON","value":{"tonWalletAddress":"0:575bedd5aa515d3b87548d933b3011c1cc462994ff5efdec2ba88ca0d233fd65","network":"tvm:-239","paymentAsset":"USDT","paymentAmount":"1000"}}}}}},"responses":{"200":{"description":"x402 payment settled and XAUH purchase request created; automated XAUH delivery may still be pending","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XauhX402PurchaseResponseDto"},"examples":{"tonMainnetUsdt":{"summary":"TON USDT payment settled; automated XAUH delivery is pending","value":{"id":"25ef38a1-c68c-460c-b6ad-05cbd3284524","userId":"faf5ce1a-5b31-49cd-9291-4d350d99e610","tonWalletAddress":"0:575bedd5aa515d3b87548d933b3011c1cc462994ff5efdec2ba88ca0d233fd65","statusUrl":"/v1/purchases/xauh/requests/25ef38a1-c68c-460c-b6ad-05cbd3284524","xauhAmount":"31.017369727047146401","xauhAmountAtomic":"31017369727047146401","xauhDecimals":18,"status":"PAYMENT_RECEIVED","deliveryStatus":"DELIVERY_PENDING","payment":{"assetSymbol":"USDT","assetAddress":"0:b113a994b5024a16719f69139328eb759596c38a25f59028b146fecdc3621dfe","network":"tvm:-239","amount":"1000","amountAtomic":"1000000000","decimals":6,"txHash":"a4609b3f00000000000000000000000000000000000000000000000000000000","explorerUrl":"https://tonviewer.com/transaction/a4609b3f00000000000000000000000000000000000000000000000000000000"},"paymentReceivedAt":"2026-08-18T15:00:00.000Z","completedAt":null,"failedAt":null,"tonTransferTxHash":null,"createdAt":"2026-08-18T14:59:57.000Z"}}}}},"headers":{"Payment-Receipt":{"description":"Base64url MPP receipt after successful settlement or a settled retry.","schema":{"type":"string"}},"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"}}}},"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","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XauhX402PaymentRequiredDto"},"examples":{"tonMainnetUsdt":{"summary":"TON USDT payment challenge with facilitator relay parameters","value":{"x402Version":2,"expiresAt":"2026-08-18T15:05:00.000Z","tonWalletAddress":"0:575bedd5aa515d3b87548d933b3011c1cc462994ff5efdec2ba88ca0d233fd65","resource":{"url":"https://api.jamton.network/v1/purchases/xauh/requests/x402","description":"Buy tokenized physical gold (XAUH) on TON through x402 using supported stablecoins.","mimeType":"application/json","serviceName":"Herculis Gold Coin","tags":["herculis","xauh","gold","rwa","ton"],"iconUrl":"https://xauh.gold/logo.png"},"accepts":[{"scheme":"exact","network":"tvm:-239","asset":"0:b113a994b5024a16719f69139328eb759596c38a25f59028b146fecdc3621dfe","amount":"1000000000","payTo":"0:1111111111111111111111111111111111111111111111111111111111111111","maxTimeoutSeconds":120,"extra":{"relayAddress":"0:7ae5000000000000000000000000000000000000000000000000000000000000","maxRelayCommission":"500000","assetDecimals":6,"assetSymbol":"USDT"}}]}}}}},"headers":{"WWW-Authenticate":{"description":"MPP evm/charge challenge for Base USDC when enabled. Follow the advertised credential header.","schema":{"type":"string"}},"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"}}}},"403":{"description":"TON beneficiary or payer wallet did not pass compliance screening","content":{"application/json":{"schema":{"type":"object","required":["message","error","statusCode"],"properties":{"message":{"type":"string"},"error":{"type":"string","example":"Forbidden"},"statusCode":{"type":"number","example":403}}},"examples":{"tonBeneficiaryComplianceRejected":{"summary":"TON beneficiary wallet did not pass compliance screening","value":{"message":"The beneficiary TON wallet did not pass compliance screening","error":"Forbidden","statusCode":403}},"tonPayerComplianceRejected":{"summary":"TON payer wallet did not pass compliance screening","value":{"message":"The payer TON wallet did not pass compliance screening","error":"Forbidden","statusCode":403}}}}}},"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":{}},{"mpp":{"method":"evm","intent":"charge","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],"price":{"mode":"dynamic","currency":"USD","min":"1"}}}}},"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":"Production x402 CAIP-2 payment network identifier. Base eip155:8453 is the default; select tvm:-239 for TON.","default":"eip155:8453","example":"eip155:8453","enum":["eip155:8453","tvm:-239"]},"paymentAsset":{"type":"string","description":"Production x402 payment asset symbol. Base supports USDC (default), USDT, and USDS; TON tvm:-239 supports USDT only. USDS uses Permit2 and requires a one-time token approval before signing.","default":"USDC","enum":["USDC","USDT","USDS"],"example":"USDS"},"paymentAmount":{"type":"string","description":"Payment amount in the configured payment asset. Exactly one of paymentAmount or xauhAmount is required. Positive plain decimal string, greater than 0 and less than 1000000000000000000. At most 64 characters and 18 integer digits (including leading zeros). No signs, whitespace, or exponent notation. Fractional precision must fit the token; trailing fractional zeros are allowed.","example":"125.45","maxLength":64,"pattern":"^(?=.{1,64}$)(?=[0-9.]*[1-9])[0-9]{1,18}(?:\\.[0-9]+)?(?![\\s\\S])"},"xauhAmount":{"type":"string","description":"Target XAUH amount. Exactly one of paymentAmount or xauhAmount is required. Positive plain decimal string, greater than 0 and less than 1000000000000000000. At most 64 characters and 18 integer digits (including leading zeros). No signs, whitespace, or exponent notation. Fractional precision must fit the token; trailing fractional zeros are allowed.","example":"0.12345","maxLength":64,"pattern":"^(?=.{1,64}$)(?=[0-9.]*[1-9])[0-9]{1,18}(?:\\.[0-9]+)?(?![\\s\\S])"}}},"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"]},"XauhX402PaymentDto":{"type":"object","properties":{"assetSymbol":{"type":"string","description":"Payment asset ticker. TON x402 settlements use USDT.","example":"USDC"},"assetAddress":{"type":"string","description":"Payment asset contract or token identifier. TON settlements expose the raw TEP-74 jetton master address.","example":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"},"network":{"type":"string","description":"x402 CAIP-2 payment network identifier, such as eip155:8453 for Base or tvm:-239 for TON","example":"eip155:8453","enum":["eip155:8453","tvm:-239"]},"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":"Verified payment settlement transaction hash on the selected payment network. Null when a TON settlement succeeded but its on-chain transaction could not be resolved.","nullable":true,"example":"0xf409875ceb8f5003b27ae7bf169b0497cf80c23c9b866a79f6cfcc17782768ce"},"explorerUrl":{"type":"string","description":"Payment settlement transaction explorer URL, using Basescan for Base or Tonviewer for TON","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 payment network identifier. Production challenges use eip155:8453 for Base or tvm:-239 for TON.","example":"eip155:8453","enum":["eip155:8453","tvm:-239"]},"asset":{"type":"string","description":"Payment asset contract or token identifier. TON USDT challenges use the raw TEP-74 jetton master address."},"amount":{"type":"string","description":"Required amount in atomic token units","example":"125450000"},"payTo":{"type":"string","description":"Merchant receiving address on the selected payment network"},"maxTimeoutSeconds":{"type":"number","description":"Maximum payment timeout in seconds. TON USDT challenges use 120 seconds.","example":300},"extra":{"type":"object","description":"Scheme-specific metadata. TON challenges include facilitator-provided relayAddress, maxRelayCommission, assetDecimals, and assetSymbol fields."}},"required":["scheme","network","asset","amount","payTo","maxTimeoutSeconds","extra"]}},"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}}}}