TRON DAO (@trondao): Building an Agentic Checkout on TRON with ACP and x402

Building an Agentic Checkout on TRON with ACP and x402 A hands-on walkthrough of ACP checkout sessions, x402 payments, and GasFree settlement on TRON Nile Agentic commerce needs two things that ordinary checkout flows were not designed for: a standard way for agents to create and track purchases, and a standard way for protected resources to request payment before access is granted. This demo combines both. Agentic Commerce Protocol, or ACP, provides the commerce layer. It defines a checkout-session style flow that an agent can use to create an order, wait for approval, move into payment, and finally confirm completion. In practical terms, ACP gives the buyer agent, merchant server, and order system a shared language for state: pending approval, ready for payment, completed, confirmed, and so on. x402 provides the payment-access layer. It builds on the long-reserved HTTP 402 Payment Required status code. A server can protect a resource, return a payment requirement, and let the client retry with a signed payment payload. In this demo, x402 settlement happens through Bank of AI’s x402 GasFree path on TRON Nile using USDT. The result is a local end-to-end demo where an ACP checkout session is created, approved, paid through x402, settled on TRON Nile, and then marked complete. Project repository: https://github.com/aziz1975/tron-acp-x402-demo What this demo runs The project runs three local services: Express API: http://localhost:8000 Python x402 service: http://localhost:8001 Vite dashboard: http://localhost:5173 The Express server owns the ACP session lifecycle and demo API. The Python service protects the premium resource with x402. The dashboard gives you a local UI for creating, approving, and paying checkout sessions. There is also an ACP explorer at: http://localhost:8000/acp-explorer Prerequisites You need: Node.js 22.12 or newer npm 10 or newer Python 3.10 or newer A TRON Nile merchant address for MERCHANT_ADDRESS A TRON Nile test wallet private key for TRON_PRIVATE_KEY Nile test TRX and TRC20 USDT for the normal agent wallet Nile test TRC20 USDT in the derived GasFree wallet Use test wallets only. Do not use a production private key. Install the demo Clone the repo and install the Node and Python dependencies: git clone https://github.com/aziz1975/tron-acp-x402-demo.git cd tron-acp-x402-demo npm install cd frontend npm install cd .. python3 -m venv .venv-x402 ./.venv-x402/bin/pip install -r requirements-x402-service.txt Configure the environment Copy the example environment file: cp .env.example .env Then edit .env: PORT=8000 SERVER_URL=http://localhost:8000 MERCHANT_ADDRESS=<your_tron_nile_merchant_address> TRON_PRIVATE_KEY=<your_tron_nile_test_wallet_private_key> TRC20_USDT_CONTRACT=TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf TRON_FULL_NODE=https://nile.trongrid.io TRON_GRID_API_KEY= FACILITATOR_URL=https://facilitator.bankofai.io X402_NETWORK=tron:nile X402_SERVICE_URL=http://localhost:8001 X402_SERVICE_PORT=8001 X402_SERVICE_RESOURCE_PATH=/premium-data X402_PRICE_DECIMAL=15.00 X402_PRICE_CURRENCY=USDT X402_SERVICE_SCHEMES=exact_gasfree The key settings are X402_NETWORK=tron:nile, X402_PRICE_DECIMAL=15.00, X402_PRICE_CURRENCY=USDT, and X402_SERVICE_SCHEMES=exact_gasfree. Together, these tell the x402 service to request a 15 USDT payment on TRON Nile using the GasFree settlement mechanism. Optional Telegram approval can be enabled with: TELEGRAM_BOT_TOKEN= TELEGRAM_CHAT_ID= Fund both wallets This demo uses two relevant wallet contexts. First, check the normal agent wallet derived from TRON_PRIVATE_KEY: npm run check:balance That wallet needs Nile test TRX and Nile test USDT. Then check the derived GasFree wallet: npm run check:gasfree If the status is not OK, copy the printed GasFree wallet address and send it enough Nile USDT for: 15.000000 USDT payment + GasFree transfer fee Run the check again: npm run check:gasfree The expected status is: Status: OK This funding step is important because the x402 payment in this demo settles through the GasFree wallet, not only the regular wallet address. Start the services Open three terminals. Terminal 1: npm run x402:service Terminal 2: npm run server Terminal 3: cd frontend npm run dev Verify the two backend services: curl http://localhost:8001/health curl http://localhost:8000/api/orders The x402 health response should include: { "network": "tron:nile", "tronFullNode": "https://nile.trongrid.io", "schemes": ["exact_gasfree"] } Open these URLs: Dashboard: http://localhost:5173 ACP explorer: http://localhost:8000/acp-explorer Orders API: http://localhost:8000/api/orders Run the dashboard flow The dashboard is the easiest way to see the ACP and x402 flow together: Open http://localhost:5173. Click New ACP Session. Approve the created session. Click Pay. Wait for GasFree settlement. Confirm the row changes to completed and shows a transaction hash. The expected completed state is: status: completed transfer_state: completed txHash: <tron_tx_hash> order.status: confirmed This is the core demo: ACP manages the commerce session, while x402 handles the payment requirement and settlement for access to the premium resource. Run the same flow with curl The same process can be driven without the dashboard. Create a checkout session: curl -X POST http://localhost:8000/agentic_commerce/checkout_sessions \ -H 'Content-Type: application/json' \ -H 'API-Version: 2026-04-17' \ -H 'Idempotency-Key: demo-create-1' \ -d '{"items":[{"id":"premium_data_access","quantity":1}]}' Approve it: curl -X POST http://localhost:8000/api/demo/approve/<checkout_session_id> Pay through x402: curl -X POST http://localhost:8000/api/demo/pay-acp-x402/<checkout_session_id> Fetch the final ACP session: curl http://localhost:8000/agentic_commerce/checkout_sessions/<checkout_session_id> The ACP checkout session collection endpoint is POST-only for creation. After you have a real session ID, use: GET /agentic_commerce/checkout_sessions/<checkout_session_id> How ACP and x402 work together here The flow starts when the dashboard creates an ACP checkout session: POST /agentic_commerce/checkout_sessions The server stores the session in orders.json with: status: pending_approval transfer_state: awaiting_human_approval payment_protocol: acp_x402_tron_usdt amount: 15 USDT At this point, ACP is doing what checkout systems need: representing the purchase intent and tracking whether a human or policy layer has approved the transaction. After approval, the session becomes: ready_for_payment The dashboard’s Pay button calls: POST /api/demo/pay-acp-x402/:id From there, Express requests the x402-protected premium resource: GET /api/premium-data?checkout_session_id=:id That request is proxied to the Python x402 service: GET http://localhost:8001/premium-data?checkout_session_id=:id The first request returns: 402 Payment Required That is the x402 moment. Instead of treating payment as a separate checkout page or manual redirect, the protected resource itself tells the client what payment is required. Express signs the x402 payload using TRON_PRIVATE_KEY, selects the exact_gasfree mechanism, and retries the request with: PAYMENT-SIGNATURE When settlement succeeds, GasFree submits a TRON Nile transaction. Express stores the transaction hash and marks the ACP checkout as: status: completed transfer_state: completed order.status: confirmed In short: ACP creates and tracks the checkout session. The approval step moves the session from intent to payment-ready. x402 protects the paid resource with an HTTP-native payment challenge. GasFree settles the USDT payment on TRON Nile. The ACP session is finalized with the resulting transaction hash. The fallback ACP TRON receipt handler is still available: POST /agentic_commerce/checkout_sessions/:id/complete Architecture overview Figure 1 shows the runtime components and how requests move from the dashboard or agent scripts into ACP, x402, GasFree, and TRON Nile. Figure 1. Runtime architecture for the TRON ACP x402 demo. The Express API owns ACP checkout sessions, stores state in orders.json, exposes the ACP payment handlers, proxies the premium resource, signs x402 payment payloads with the TRON test wallet, and records the resulting settlement back onto the ACP session. UML sequence diagram Figure 2 follows the happy path after a buyer agent or the dashboard creates a checkout session and the merchant approval step has allowed payment.