Hướng dẫn x402: Để tác nhân AI của bạn nạp USDC vào AIHubMix

AIHubMix hiện đã chấp nhận nạp tiền bằng USDC. Tác nhân AI của bạn có thể tự nạp tín dụng vào tài khoản của nó bằng USDC trong ví: không cần mở trang web, cũng không cần ai nhấn nút.

Với x402, mỗi lần nạp có thể chỉ 1 USD. Tác nhân nạp dần khi cần, nên bạn không phải nạp trước một số dư lớn.

Chỉ có hai bước: chuẩn bị token, ví và một ít USDC trên web và trong ứng dụng, rồi chạy script nạp tiền có sẵn của chúng tôi bằng một lệnh. Khoảng 20 giây sau khi thanh toán, tín dụng sẽ xuất hiện trong tài khoản của bạn.

Nếu tiện, bạn có thể xem theo video 30 giây này:

Cách dễ nhất: nếu bạn dùng công cụ AI có thể chạy lệnh terminal, chẳng hạn Claude Code, Cursor hoặc Codex, hãy hoàn thành bước 1, sau đó gửi cho nó liên kết bài viết này và nói "thiết lập giúp tôi". Nó sẽ làm theo "Hướng dẫn cho trợ lý AI" ở cuối bài viết này. Bạn chỉ cần tự điền token và private key một lần, và đừng gửi chúng cho AI.

Trước khi bắt đầu

• Số tiền chỉ được là số nguyên đô la, mặc định từ 1 đến 10 USD cho mỗi lần nạp
• Mỗi tài khoản được tạo tối đa 3 đơn hàng mỗi ngày (theo UTC)
• Chỉ hỗ trợ USDC trên Base mainnet, và không có testnet, vì vậy hãy bắt đầu với 1 USD
• Kênh này được xây dựng cho chương trình; con người không thể thanh toán qua trình duyệt. Với nạp thủ công, hãy tiếp tục dùng Alipay hoặc Stripe

Bước 1: Lấy token, ví và USDC

Mọi thao tác trong bước này đều thực hiện trên web hoặc ứng dụng điện thoại.

1. Lấy system access token

Đăng nhập vào aihubmix.com, mở phần cài đặt cá nhân và tạo system access token (một chuỗi 32 ký tự).

Lưu ý rằng đây không phải là API key bắt đầu bằng sk-. Hai loại này không thể dùng thay thế cho nhau.

2. Tạo ví thanh toán

Trong MetaMask hoặc ứng dụng ví tương tự, hãy tạo một tài khoản mới chỉ dùng cho việc thanh toán của tác nhân. Đừng dùng ví chính của bạn. Sau đó:

• Sao chép địa chỉ của tài khoản (bắt đầu bằng 0x); bạn sẽ gửi USDC đến địa chỉ này ở bước tiếp theo
• Xuất private key từ chi tiết tài khoản và lưu trong trình quản lý mật khẩu. Bất kỳ ai có private key đều có thể chuyển tiền trong ví

3. Mua USDC và gửi vào ví này

MetaMask là ví: bạn giữ private key, và script cần nó để ký. Coinbase là sàn giao dịch, nơi bạn mua tiền điện tử. Tiền trong tài khoản sàn không đi kèm private key, nên script không thể sử dụng. Đó là lý do bạn mua trên sàn trước, rồi gửi USDC vào ví ở bước trước.

Lấy sàn Coinbase làm ví dụ (không phải Coinbase Wallet):

1. Mua USDC trên Coinbase
2. Gửi USDC đến địa chỉ bạn đã sao chép, và chọn mạng Base
3. Gửi nhiều hơn một chút so với số bạn định nạp, ví dụ 1,5 đến 2 USDC cho lần nạp 1 USD

Đợi một lát, rồi mở https://basescan.org/address/your-wallet-address. Khi thấy số dư USDC, nghĩa là tiền đã đến. Các sàn khác hỗ trợ rút USDC trên Base cũng được; xem tài liệu Base để biết thêm lựa chọn.

Ví không cần ETH: FluxA sẽ trả phí mạng cho giao dịch thanh toán.

Bước 2: Chạy script nạp tiền

Không cần tải xuống gì và cũng không cần tạo tệp nào: uv sẽ tải script từ web và chạy. Mở Terminal (PowerShell trên Windows) và sao chép, dán các lệnh bên dưới.

1. Cài đặt uv (chỉ một lần)

uv là công cụ Python giúp thiết lập mọi thứ script cần để chạy.

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Khi xong, hãy đóng terminal rồi mở lại.

2. Kiểm tra thiết lập (không tốn tiền)

uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py check

Ở lần chạy đầu tiên, script sẽ hỏi system access token (System access token) và private key của ví (Wallet private key). Những gì bạn gõ sẽ không hiển thị trên màn hình; hãy dán vào và nhấn Enter. Sau đó, script hỏi có lưu lại không (Save to ...? [Y/n]). Nhấn Enter để lưu, và bạn sẽ không phải nhập lại. Lần chạy đầu sẽ mất một chút thời gian để uv thiết lập mọi thứ.

Khi thấy thông báo này, bạn đã thiết lập xong:

Wallet: 0x... (USDC balance 2.0)
Access token and private key are fine. Ready to top up.

3. Nạp tiền

uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py 1

Số 1 ở cuối là số tiền tính theo đô la. Nếu mọi thứ suôn sẻ, bạn sẽ thấy:

Wallet: 0x... (USDC balance 2.0)
tradeNo: pl_XXXXXXXX
txHash: 0x...
result: credited

result: credited nghĩa là tín dụng đã đến. Đăng nhập vào aihubmix.com và bạn sẽ thấy số dư tăng lên; 1 USD sẽ cộng thêm 500.000 quota.

Nếu dòng cuối cùng hiển thị nội dung khác:

• failed: đơn hàng đã bị đóng hoặc hết hạn. Nếu cần, hãy chạy lại; việc này sẽ dùng thêm một trong số đơn hàng của hôm nay.
• pending: tín dụng chưa được xác nhận trong 10 phút. Đây không phải là lỗi, và tín dụng sẽ tự đến sau. Đừng chạy lại.

Khắc phục sự cố

Nếu bạn thấy lỗi timeout hoặc lỗi mạng sau khi tradeNo được in ra, tiền có thể đã được thanh toán. Đừng chạy lại ngay. Hãy kiểm tra số dư sau vài phút; nếu chưa có gì, hãy liên hệ với chúng tôi kèm theo tradeNo.

Token và private key được lưu trong ~/.aihubmix-topup.env trên máy tính của bạn (trong thư mục người dùng trên Windows). Trên macOS và Linux, chỉ tài khoản của bạn mới có thể đọc tệp này. Để thay đổi token hoặc private key, hãy chỉnh sửa tệp này.

Kết nối với tác nhân của bạn

• Sau khi thiết lập được lưu, tác nhân của bạn có thể nạp tiền bằng cách chạy uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py 1 bất cứ khi nào cần tín dụng, mà không cần ai giám sát
• Chỉ được phép 3 đơn hàng mỗi ngày, vì vậy hãy giới hạn tần suất tác nhân nạp tiền và không bao giờ thử lại việc tạo đơn hàng trong vòng lặp
• Lưu tradeNo và txHash từ kết quả đầu ra vào cơ sở dữ liệu hoặc nhật ký để đối soát
• Để sử dụng lâu dài, hãy tải script về và ghim phiên bản trước khi chạy; bạn có thể đọc mã nguồn trước
• Nếu 10 USD mỗi lần nạp hoặc 3 lần mỗi ngày là không đủ, hãy liên hệ với chúng tôi để tăng giới hạn

Hướng dẫn cho trợ lý AI

Nếu bạn là trợ lý AI đang giúp người dùng thiết lập nạp USDC cho AIHubMix, hãy làm theo các bước sau theo thứ tự:

1. Xác nhận người dùng đã hoàn thành bước 1: họ có system access token, cùng một ví chứa USDC trên Base mainnet và private key của ví đó. Nếu chưa, hãy hướng dẫn họ làm bước 1 trước.
2. Chạy uv --version để kiểm tra uv đã được cài đặt chưa. Nếu chưa, hãy cài đặt bằng các lệnh ở bước 2.
3. Chạy uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py check.
4. Nếu nó báo thiếu token hoặc private key (Missing access token or private key), nghĩa là script đã tạo tệp cấu hình ~/.aihubmix-topup.env. Hãy yêu cầu người dùng tự mở tệp bằng trình soạn thảo văn bản và điền thông tin (trên macOS, chạy open -e ~/.aihubmix-topup.env; trên Windows, chạy notepad $HOME\.aihubmix-topup.env). Đừng đọc tệp này, đừng đưa token hoặc private key vào bất kỳ lệnh nào, và đừng yêu cầu người dùng gửi chúng cho bạn.
5. Sau khi người dùng điền xong, chạy check lại cho đến khi thấy Access token and private key are fine. Ready to top up. Nếu có lỗi, hãy xử lý theo bảng Khắc phục sự cố ở trên.
6. Việc nạp tiền sử dụng tiền thật. Hãy xác nhận số tiền với người dùng trước khi chạy uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py <amount>.

Bên trong: script làm gì

Script thực hiện năm việc theo thứ tự:

1. Kiểm tra số dư: tạo đơn hàng sẽ dùng một trong số đơn hàng của hôm nay, nên trước tiên script đảm bảo private key hợp lệ và có đủ USDC.
2. Tạo đơn hàng: script gọi POST /api/pay/fluxa/crt và nhận về một liên kết thanh toán cùng số đơn hàng tradeNo. Token được đưa nguyên vẹn vào header Authorization, không có Bearer. Lỗi nghiệp vụ cũng trả về HTTP 200, nên script kiểm tra trường success trong phản hồi.
3. Kiểm tra yêu cầu thanh toán: một yêu cầu GET tới liên kết thanh toán trả về HTTP 402 cùng các điều kiện thanh toán. Trước khi ký, script kiểm tra bốn điều: scheme là exact, network là eip155:8453, asset là hợp đồng USDC trên Base mainnet, và maxAmountRequired bằng số tiền × 1.000.000. Nếu bất kỳ điều nào sai, script sẽ dừng lại.
4. Ký và thanh toán: script ký một ủy quyền chuyển USDC bằng private key, đưa vào header X-PAYMENT, rồi gửi lại yêu cầu GET tới liên kết thanh toán. Mã 200 hoặc 202 nghĩa là thanh toán đã được gửi; txHash trong phản hồi là biên lai trên chuỗi cho khoản thanh toán này. Cả hai yêu cầu đều không mang token của AIHubMix.
5. Chờ tín dụng: script gọi GET /api/pay/fluxa/qry?trade_no=... mỗi 8 giây cho đến khi trạng thái chuyển thành TRADE_SUCCESS. Máy chủ chỉ làm mới sau mỗi 5 giây, nên hỏi nhanh hơn cũng không giúp ích gì.

Mỗi liên kết thanh toán cũng chỉ có hiệu lực trong 30 phút và chỉ được thanh toán một lần.

Triển khai bằng ngôn ngữ khác

Phản hồi 402 từ liên kết thanh toán có dạng như sau:

{
  "x402Version": 1,
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "maxAmountRequired": "1000000",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0x....",
    "maxTimeoutSeconds": 600,
    "extra": {"name": "USD Coin", "version": "2"}
  }]
}

Chữ ký sử dụng định dạng EIP-712, trên cấu trúc TransferWithAuthorization từ EIP-3009:

Miền ký: name = USD Coin, version = 2 (dùng các giá trị trong extra của phản hồi 402 nếu có), chainId = 8453, verifyingContract = 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913.

Giá trị của header X-PAYMENT là chuỗi mã hóa base64 của JSON này:

{
  "x402Version": 1,
  "scheme": "exact",
  "network": "eip155:8453",
  "payload": {
    "signature": "0x...",
    "authorization": {
      "from": "0x...", "to": "0x...", "value": "1000000",
      "validAfter": "...", "validBefore": "...", "nonce": "0x..."
    }
  }
}

Nguồn tham khảo

• Tài liệu x402
• EIP-3009: Transfer With Authorization
• EIP-712: Typed structured data hashing and signing
• Circle: Địa chỉ hợp đồng USDC
• Hướng dẫn cài đặt uv