# 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. At the moment, paid requests are processed manually by the Herculis provider. Automated request processing is planned and will be delivered later. ## 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 `USDT`. | | `paymentAmount` | Conditional | Decimal payment amount in the selected payment token. Exactly one of `paymentAmount` or `xauhAmount` is required. | | `xauhAmount` | Conditional | Decimal target amount of XAUH. Exactly one of `paymentAmount` or `xauhAmount` is required. | Example: ```json { "tonWalletAddress": "0:575bedd5aa515d3b87548d933b3011c1cc462994ff5efdec2ba88ca0d233fd65", "network": "eip155:8453", "paymentAsset": "USDT", "xauhAmount": "0.25" } ``` ## 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` | `USDT` | [`0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2`](https://basescan.org/token/0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2) | `permit2` | Yes | | Base Mainnet, `eip155:8453` | `USDC` | [`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`](https://basescan.org/token/0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913) | `eip3009` | 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. ## Unpaid Response Unpaid or unverified requests return HTTP `402`. Headers: ```http PAYMENT-REQUIRED: ``` Body shape: ```json { "x402Version": 2, "quoteId": "b6b9a11d-70ad-4dde-8d75-2f57c6c2b46a", "expiresAt": "2026-05-19T12:05:00.000Z", "tonWalletAddress": "0:575bedd5aa515d3b87548d933b3011c1cc462994ff5efdec2ba88ca0d233fd65", "resource": { "url": "https://api.jamton.network/v1/purchases/xauh/requests/x402", "description": "Purchase XAUH with x402", "mimeType": "application/json" }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2", "amount": "8060000", "payTo": "0xMerchantAddress", "maxTimeoutSeconds": 300, "extra": { "assetTransferMethod": "permit2" } } ], "extensions": { "xauh": { "amount": "250000000000000000", "amountDisplay": "0.25" } } } ``` `quoteId` is short-lived. If the quote expires, create a new unpaid request and use the new payment requirements. ## 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", "tonWalletAddress": "0:575bedd5aa515d3b87548d933b3011c1cc462994ff5efdec2ba88ca0d233fd65", "xauhAmount": "250000000000000000", "xauhAmountDisplay": "0.25", "status": "PAYMENT_RECEIVED" } ``` The real response includes the complete `XauhPurchaseRequestDto` described in the [x402 OpenAPI spec](./x402-openapi.json). ## XAUH Delivery After payment settlement, the request status is `PAYMENT_RECEIVED`. At the moment, XAUH delivery is processed manually by the Herculis provider, so the TON recipient does not receive XAUH immediately after the x402 payment succeeds. Agents should store the returned purchase request `id`, `tonWalletAddress`, and `xauhAmountDisplay` for user-facing status tracking. Automated request processing is planned and will be delivered later. ## 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 same `XauhPurchaseRequestDto` shape returned by the paid x402 retry. The most important field for agents is `status`: | Status | Meaning for an external user or agent | |--------------------|---------------------------------------------------------------------------------------------------------| | `PAYMENT_RECEIVED` | The x402 payment was settled and the request is waiting for manual processing by the Herculis provider. | | `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. | ### 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)