# 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) ## 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 EVM network identifier. Production uses Base mainnet, `eip155:8453`. | | `paymentAsset` | No | Payment token symbol. Production defaults to `USDC`. Use `USDT` only when explicitly requested. | | `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. | Example: ```json { "tonWalletAddress": "0:575bedd5aa515d3b87548d933b3011c1cc462994ff5efdec2ba88ca0d233fd65", "network": "eip155:8453", "paymentAsset": "USDC", "paymentAmount": "1000" } ``` ## Production Purchase Limits Production x402 purchases must be at least `1` selected payment asset unit, for example `1 USDC` or `1 USDT`. 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 | Transfer method | Default | |-----------------------------|--------|-----------------------------------------------------------------------------------------------------------------------|-----------------|---------| | Base Mainnet, `eip155:8453` | `USDC` | [`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`](https://basescan.org/token/0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913) | `eip3009` | Yes | | Base Mainnet, `eip155:8453` | `USDT` | [`0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2`](https://basescan.org/token/0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2) | `permit2` | No | ## 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. 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. ## 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" } } ], "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 generic purchase request status resource, not the x402 paid response DTO. 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 EVM account that pays the x402 invoice and the TON wallet that receives XAUH are separate identities. A wallet, sender, or AI agent can pay from an EVM address and specify `tonWalletAddress` as the TON recipient. The purchase request is created for that TON recipient after the x402 payment is settled. ## 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)