# Buy XAUH With x402 This document is the agent-facing integration guide for buying XAUH through the x402 payment flow. Use it together with the dedicated [x402 OpenAPI spec](./x402-openapi.json). ## Production API Production base URL: [`https://api.jamton.network/v1`](https://api.jamton.network/v1) Production x402 purchase endpoint: [ `https://api.jamton.network/v1/purchases/xauh/requests/x402`](https://api.jamton.network/v1/purchases/xauh/requests/x402) ## Relationship To Website Purchases The x402 flow is separate from [browser cryptocurrency purchases](/buy/crypto). The browser flow offers ChangeNOW and Changelly through an explicit provider selector, with ChangeNOW selected by default. New requests submit `CHANGENOW` or `CHANGELLY` with that provider's metadata and a UUID `idempotencyKey`; there is no automatic provider fallback. The shared purchase-status API and `/buy/{requestId}` web route are provider-neutral. Their provider field can contain `CHANGENOW`, `CHANGELLY`, `WERT`, or `X402`. Pending browser attempts retain the accepted provider, request, and UUID across same-tab reloads and explicit status checks. Do not replace an uncertain attempt with a new purchase. ## What Success Means A successful x402 payment creates an XAUH purchase request for the TON wallet in `tonWalletAddress`. It does not immediately transfer XAUH to that wallet. After payment settlement, automated XAUH delivery continues asynchronously. The paid response may initially report `status: PAYMENT_RECEIVED` and `deliveryStatus: DELIVERY_PENDING`; agents should poll the returned `statusUrl` until a terminal status. `COMPLETED` confirms delivery, and `tonTransferTxHash` is exposed when available. ## Endpoint `POST /purchases/xauh/requests/x402` Authentication is optional. A JWT can identify an existing JAMTON user, but autonomous agents should send `tonWalletAddress` explicitly so the purchased XAUH jettons can be delivered on TON. ## Request Body | Field | Required | Description | | ------------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tonWalletAddress` | Conditional | TON wallet address that will receive the purchased XAUH jettons. Required when the request is not tied to a JWT user that already has a TON wallet. | | `network` | No | CAIP-2 payment network. Production supports Base mainnet `eip155:8453` (default) and TON mainnet `tvm:-239`. | | `paymentAsset` | No | Payment token symbol. Base supports `USDC` (default), `USDT`, and `USDS`; TON supports explicitly selected `USDT` only. | | `paymentAmount` | Conditional | Decimal payment amount in the selected payment token. Exactly one of `paymentAmount` or `xauhAmount` is required. Must meet the production minimum. | | `xauhAmount` | Conditional | Decimal target amount of XAUH. Exactly one of `paymentAmount` or `xauhAmount` is required. The converted payment amount must meet the production minimum. | Base USDC request example (the Base response examples below use this route): ```json { "tonWalletAddress": "0:575bedd5aa515d3b87548d933b3011c1cc462994ff5efdec2ba88ca0d233fd65", "network": "eip155:8453", "paymentAsset": "USDC", "paymentAmount": "1000" } ``` Base USDS request example (explicit selection after one-time Permit2 approval): ```json { "tonWalletAddress": "0:575bedd5aa515d3b87548d933b3011c1cc462994ff5efdec2ba88ca0d233fd65", "network": "eip155:8453", "paymentAsset": "USDS", "xauhAmount": "0.25" } ``` ## Production Purchase Limits Production x402 purchases must be at least `1` selected payment asset unit, for example `1 USDC`, `1 USDT`, or `1 USDS`. Requests made with `xauhAmount` are accepted only when the quote converts that XAUH amount into at least the production minimum payment amount for the selected asset. ## Supported Payment Assets The payment requirements returned by the API are authoritative. The current registry supports these assets: | Network | Symbol | Contract or jetton master | Decimals | Minimum | Transfer method | Default | Timeout | | --------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | --------------- | ------- | ------- | | Base Mainnet, `eip155:8453` | `USDC` | [`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`](https://basescan.org/token/0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913) | 6 | `1` | `eip3009` | Yes | 300 s | | Base Mainnet, `eip155:8453` | `USDT` | [`0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2`](https://basescan.org/token/0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2) | 6 | `1` | `permit2` | No | 300 s | | Base Mainnet, `eip155:8453` | `USDS` | [`0x820c137fa70c8691f0e44dc420a5e53c168921dc`](https://basescan.org/token/0x820c137fa70c8691f0e44dc420a5e53c168921dc) | 18 | `1` | `permit2` | No | 300 s | | TON Mainnet, `tvm:-239` | `USDT` | [`0:b113a994b5024a16719f69139328eb759596c38a25f59028b146fecdc3621dfe`](https://tonviewer.com/0:b113a994b5024a16719f69139328eb759596c38a25f59028b146fecdc3621dfe) | 6 | `1` | TEP-74 relay | No | 120 s | USDS payments require a one-time Permit2 token approval before the first x402 payment. USDS is available on Base mainnet only; it is not supported on Base Sepolia. The minimum purchase payment is 1 unit of the selected payment asset. ## Discovery And Asset Selection Read the [x402 discovery manifest](https://api.jamton.network/.well-known/x402) or its [JSON alias](https://api.jamton.network/.well-known/x402.json) to discover the purchase resource. An empty `GET` or `POST` with body `{}` to the purchase endpoint returns HTTP `402` with synthetic discovery metadata. Decode the base64 `PAYMENT-REQUIRED` header and inspect its `accepts` array alongside the response body's `accepts`. The supported-asset matrix above describes explicit purchase requests; discovery responses are not guaranteed to enumerate every supported asset. Do not assume the manifests and empty probes contain identical alternatives. For a purchase, explicitly select `network` and `paymentAsset`, provide the recipient and exactly one amount field, and request a fresh unsigned quote. Use only its matching requirement, including `extra.xauhQuoteId`, unchanged. If that route is rejected, stop; do not construct a payment from documentation or discovery examples. Discovery probes have no quote ID and cannot be paid directly. Discovery does not prove payment settlement or XAUH delivery and is not authorization to spend funds. ## Flow 1. Call `POST` against the [production x402 purchase endpoint](https://api.jamton.network/v1/purchases/xauh/requests/x402) without a payment signature. 2. The API returns HTTP `402` and a `PAYMENT-REQUIRED` header containing a base64-encoded x402 `PaymentRequired` payload. For a real purchase, preserve the complete selected `accepts` entry as `PaymentPayload.accepted`, including `extra.xauhQuoteId` and any additional metadata, and preserve the original `resource`. Do not reconstruct these objects from an example. Empty discovery probes omit the quote ID and cannot be paid directly. 3. The payer signs or submits the required payment using an x402-compatible wallet, SDK, or agent. 4. Retry the same endpoint with the signed payment payload in `PAYMENT-SIGNATURE`. The legacy `X-PAYMENT` request header is accepted only as an SDK compatibility alias. 5. The API verifies and settles the payment through the configured x402 facilitator. 6. On success, the API returns HTTP `200`, a `PAYMENT-RESPONSE` header containing the base64-encoded settlement response, and an XAUH purchase request. This confirms that the payment was received and the delivery request was accepted. It does not mean the XAUH jettons have already arrived in the TON wallet; automated delivery continues asynchronously. ## TON USDT Example For a TON payment, explicitly select TON mainnet and USDT. The payer wallet may differ from `tonWalletAddress`, which is always the recipient of the purchased XAUH. ```json { "tonWalletAddress": "0:575bedd5aa515d3b87548d933b3011c1cc462994ff5efdec2ba88ca0d233fd65", "network": "tvm:-239", "paymentAsset": "USDT", "paymentAmount": "1000" } ``` The unpaid request returns HTTP `402`. Its `accepts[0]` requirement uses the raw TEP-74 USDT jetton master, six decimals, and a 120-second timeout. `payTo` is the merchant payment recipient; it is not the XAUH delivery wallet. ### TON unpaid response example All following values are illustrative, not a live quote. Obtain addresses, relay metadata, quote ID, resource, and expiry from a fresh server response; never sign the sample values. ```json { "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" }, "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", "xauhQuoteId": "3f3af438-0d78-4ae4-bfa4-d37078555228" } } ] } ``` ### TON signed retry example Sign the requirement with the TON payer wallet and retry the same request with a base64-encoded `PaymentPayload` in `PAYMENT-SIGNATURE`. Copy `resource` and the selected requirement unchanged, including `extra.xauhQuoteId`; omitting the ID returns another `402` with `No matching x402 payment quote`, not settlement. The decoded TON payload has this shape: ```json { "x402Version": 2, "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" }, "accepted": { "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", "xauhQuoteId": "3f3af438-0d78-4ae4-bfa4-d37078555228" } }, "payload": { "signedBoc": "", "walletPublicKey": "<32-byte public key as hex>", "walletAddress": "", "seqno": 1, "validUntil": 1773502200 } } ``` ### TON settled-payment example Successful settlement returns HTTP `200` and `PAYMENT-RESPONSE: `. The TON payment transaction below is separate from the later XAUH delivery transaction. A paid response is not completed delivery: ```json { "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" } ``` Resolve `statusUrl` against the API origin and poll the same purchase until `status` is `COMPLETED` and `tonTransferTxHash` identifies the XAUH delivery transaction. Never start a replacement payment to recover delayed delivery. ## Unpaid Response Unpaid or unverified requests return HTTP `402`. Headers: ```http PAYMENT-REQUIRED: ``` Body shape: ```json { "x402Version": 2, "expiresAt": "2026-05-19T12: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. Payment settlement creates a purchase request; automated delivery continues asynchronously and can be tracked through statusUrl until COMPLETED.", "mimeType": "application/json" }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "1000000000", "payTo": "0xMerchantAddress", "maxTimeoutSeconds": 300, "extra": { "name": "USD Coin", "version": "2", "assetTransferMethod": "eip3009", "xauhQuoteId": "58305ed3-93ce-422c-a288-641c162b067e" } } ], "extensions": { "xauh": { "tonWalletAddress": "0:575bedd5aa515d3b87548d933b3011c1cc462994ff5efdec2ba88ca0d233fd65", "xauhAmount": "31.017369727047146401", "xauhAmountAtomic": "31017369727047146401", "xauhDecimals": 18, "docs": { "llmsTxtUrl": "https://xauh.gold/llms.txt", "llmsFullTxtUrl": "https://xauh.gold/llms-full.txt", "guideUrl": "https://xauh.gold/ai/x402-xauh-purchase.md", "openApiUrl": "https://xauh.gold/ai/x402-openapi.json" } } } } ``` The payment requirements are short-lived. If they expire, create a new unpaid request and use the new payment requirements. The `extensions.bazaar` discovery metadata is included only when Bazaar discovery is enabled; agents should rely on `extensions.xauh` for XAUH-specific metadata. The sample response values use a `1000 USDC` quote. Actual XAUH output is quote- and rate-dependent. ## Paid Retry Send the signed x402 payment payload back to the same endpoint: ```http PAYMENT-SIGNATURE: ``` Successful settlement returns HTTP `200`. Treat this response as payment confirmation and purchase request creation, not as final XAUH delivery confirmation. Headers: ```http PAYMENT-RESPONSE: ``` Body: ```json { "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": "USDC", "assetAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "network": "eip155:8453", "amount": "1000", "amountAtomic": "1000000000", "decimals": 6, "txHash": "0xf409875ceb8f5003b27ae7bf169b0497cf80c23c9b866a79f6cfcc17782768ce", "explorerUrl": "https://basescan.org/tx/0xf409875ceb8f5003b27ae7bf169b0497cf80c23c9b866a79f6cfcc17782768ce" }, "paymentReceivedAt": "2026-06-12T13:39:48.237Z", "completedAt": null, "failedAt": null, "tonTransferTxHash": null, "createdAt": "2026-06-12T13:39:45.690Z" } ``` The real response includes the complete `XauhX402PurchaseResponseDto` described in the [x402 OpenAPI spec](./x402-openapi.json). The sample XAUH amount is illustrative; production output depends on the quote's XAU/USD rate snapshot. ## XAUH Delivery After payment settlement, the response normally reports `status: PAYMENT_RECEIVED` and `deliveryStatus: DELIVERY_PENDING`. These are non-terminal states: automated processing continues asynchronously and the TON recipient should not expect XAUH to arrive instantly after the x402 payment succeeds. Agents should store the returned purchase request `id`, `statusUrl`, `tonWalletAddress`, `xauhAmount`, `xauhAmountAtomic`, and `payment.txHash` for user-facing status tracking. Poll `statusUrl` until a terminal status. `COMPLETED` confirms XAUH delivery, and `tonTransferTxHash` is exposed when the transfer hash is available. ## Checking Request Status Use the purchase request `id` from the paid response to check delivery progress. ### API API polling endpoint: [ `GET https://api.jamton.network/v1/purchases/xauh/requests/{requestId}`](https://api.jamton.network/v1/purchases/xauh/requests/{requestId}) ```http GET https://api.jamton.network/v1/purchases/xauh/requests/{requestId} ``` The response is the provider-neutral purchase request status resource, not the x402 paid response DTO. It is shared with ChangeNOW and Changelly website purchases, including historical records. The provider identifies the order; it does not select a provider for a new purchase. The most important field for agents is `status`: | Status | Meaning for an external user or agent | | ------------------ | --------------------------------------------------------------------------------------------------- | | `PAYMENT_RECEIVED` | The x402 payment was settled and automated XAUH delivery is continuing asynchronously. | | `COMPLETED` | XAUH delivery has been completed. If available, `tonTransferTxHash` contains the TON transfer hash. | | `FAILED` | The request failed. Check `failureReason` when it is present. | | `CANCELLED` | The request was cancelled. Check `cancellationReason` when it is present. | | `PENDING` | The request exists, but payment or processing has not reached a later state yet. | In the x402 paid response, `deliveryStatus: DELIVERY_PENDING` is the delivery-specific form of the same non-terminal phase. Continue polling instead of treating it as a failure or final delivery confirmation. ### Web UI Open the purchase page at [`https://xauh.gold/buy/{requestId}`](https://xauh.gold/buy/{requestId}), replacing `{requestId}` with the returned purchase request `id`. ## Recipient Model The wallet that pays the x402 invoice and the TON wallet that receives XAUH are separate identities. A wallet, sender, or AI agent can pay from Base or TON and specify a different `tonWalletAddress` as the XAUH recipient. For TON payment requirements, `payTo` is the merchant payment recipient and the signed payload identifies the payer; `tonWalletAddress` remains the delivery recipient. ## Idempotency The settlement transaction is guarded against duplicate fulfillment. If the same settled payment is retried, the endpoint returns the existing fulfilled purchase request instead of creating another one. ## Protocol References - [x402 HTTP 402 headers](https://docs.x402.org/core-concepts/http-402) - [x402 facilitator flow](https://docs.x402.org/core-concepts/facilitator) - [x402 network and token support](https://docs.x402.org/core-concepts/network-and-token-support)