TRON DAO (@trondao): Getting Started with the TRON UCP x402

Getting Started with the TRON UCP x402 UCP is a way for software to describe a checkout flow in a machine-friendly format. x402 is a way to protect a paid API route and let a client know that payment is required. In this project, both are demonstrated on TRON Nile in a local setup. What You Will Run This demo uses three local processes. The first is a Python service that protects a premium endpoint with x402. The second is a Node.js server that exposes the UCP endpoints, proxies the premium route, and stores orders. The third is a frontend dashboard that lets you watch orders and trigger the demo agent from the browser. What You Need You need Node.js 22 or newer, npm 10 or newer, and Python 3.10 or newer. You also need a TRON Nile merchant wallet address, a TRON Nile test private key for the agent wallet, some Nile TRX, and some Nile TRC20 USDT. Telegram is optional. It is only needed if you want live approval prompts during the UCP checkout flow. Clone the Repository Start by cloning the repo and entering the project folder. git clone https://github.com/aziz1975/tron-ucp-x402-demo.git cd tron-ucp-x402-demo Install the Dependencies Install the main Node.js dependencies first. npm install Then install the frontend dependencies. cd frontend npm install cd .. Now create a Python virtual environment and install the dependencies for the x402 middleware service. python3 -m venv .venv-x402 ./.venv-x402/bin/pip install -r requirements-x402-service.txt Create the Environment File Copy the sample environment file. cp .env.example .env Then edit .env and set the local values. PORT=8000 MERCHANT_ADDRESS=TYourMerchantWalletAddress TRON_PRIVATE_KEY=your_nile_test_agent_private_key TRC20_USDT_CONTRACT=TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf 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_permit TELEGRAM_BOT_TOKEN=your_bot_token TELEGRAM_CHAT_ID=your_chat_id For the premium x402 route, the key values are the merchant address, the agent private key, the facilitator URL, and the x402 service URL. Check the Agent Wallet Before testing payments, make sure the buyer wallet has funds. node check-balance.js A good result shows the agent wallet address, the TRX balance, and the TRC20 USDT balance. Start the Services Open three terminals. In the first terminal, start the Python x402 middleware service. ./.venv-x402/bin/python x402_service.py It should start on port 8001. You can confirm it is alive with a quick health request. curl http://localhost:8001/health In the second terminal, start the Express server. node server.js When it starts, you should see the premium route, the x402 upstream service, and the UCP business profile URL in the logs. In the third terminal, start the frontend dashboard. cd frontend npm run dev Then open http://localhost:5173 in your browser. Test the x402 Premium Route The simplest way to begin is to hit the Python service directly. curl -i http://localhost:8001/premium-data The expected result is an HTTP 402 Payment Required response with an x402 challenge. Next, hit the same premium route through the Node.js server. curl -i http://localhost:8000/api/premium-data The expected result is another HTTP 402 Payment Required response, this time forwarded through the Express proxy. Now run the demo agent. node test-agent.js The flow is straightforward. The first request gets a payment challenge. The client signs the payment payload. The request is retried with the payment signature. The facilitator verifies the payment. The final response returns the premium payload. After the payment succeeds, confirm that the order was recorded. curl http://localhost:8000/api/orders You should see a new order marked as paid, with the payment protocol set to bankofai_x402. If settlement completed successfully, you should also see a transaction hash. You can also verify the same result from the dashboard. The Payments view should show the new paid order, and the Run Live Demo Agent button should trigger the same flow visually. Test the UCP Checkout Flow The UCP flow is a separate checkout session flow. Start by creating a checkout session. curl -X POST http://localhost:8000/ucp/v1/checkout-sessions \ -H "Content-Type: application/json" \ -d '{"line_items":[{"item":{"id":"premium_data_access"},"quantity":1}]}' The server returns JSON for the new checkout session. In that response, the session ID is the checkout_session_id field. The expected result is HTTP 201 Created. The new order should begin in the AWAITING_2FA state. If Telegram is configured, approve the request there. If not, use the local fallback endpoint. curl -X POST http://localhost:8000/api/demo/approve-2fa/<checkout_session_id> After approval, the order should move to PENDING. Now poll the checkout session. curl http://localhost:8000/ucp/v1/checkout-sessions/<checkout_session_id> The expected result is a transfer state of ready_for_transfer. To finish the flow, submit a real TRON transaction hash. curl -X POST http://localhost:8000/ucp/v1/checkout-sessions/<checkout_session_id>/complete \ -H "Content-Type: application/json" \ -d "{"transactionHash":"<real_tron_tx_hash>"}" At that point, the server verifies the recipient, amount, and token contract. If everything matches, the checkout session is marked as paid. If Something Breaks If the Python premium route does not return 402, make sure the x402 service is running, the environment file exists, the merchant address is valid, and the Python dependencies were installed correctly. If the demo agent fails because of insufficient balance, fund the buyer wallet with Nile TRX and Nile TRC20 USDT, then rerun the balance check. If /api/premium-data returns 502, the Express server probably cannot reach the Python service. Check the x402 service URL, the resource path, and confirm that the Python service is listening on port 8001. If Telegram approval does not appear, check the bot token, the chat ID, and make sure the bot has received /start. If needed, use the local approval endpoint and continue testing. Final Thoughts This demo is easiest to understand when you treat it as two hands-on exercises in one repo. First, prove that the premium x402 route works end to end. Then run the UCP checkout session flow separately. Once both flows work locally, the project becomes much easier to reason about.