Bộ kích hoạt — kích hoạt địa chỉ

Kích hoạt một địa chỉ TRON chưa từng được sử dụng trên chuỗi. Một địa chỉ hoàn toàn mới chưa có bản ghi tài khoản, do đó nó không thể nhận ủy quyền năng lượng (energy) hoặc băng thông (bandwidth) cho đến khi được kích hoạt. Điểm cuối này tạo tài khoản giúp bạn và trả về mã băm (hash) giao dịch kích hoạt.

Kích hoạt là một thao tác một lần duy nhất cho mỗi địa chỉ. Nếu địa chỉ đã hoạt động, điểm cuối sẽ thông báo cho bạn và không tính phí.

URL cơ sở của Endpoint

https://netts.io/apiv2/activator

Headers của yêu cầu

Header	Required	Description
Content-Type	Có	application/json
X-API-KEY	Có	Khóa API của bạn từ bảng điều khiển Netts

user_id của bạn được suy ra từ khóa API — bạn không bao giờ phải truyền nó.

Kích hoạt — `POST /apiv2/activator`

Body của yêu cầu

json

{ "targetAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE" }

Trường	Type	Required	Description
`targetAddress`	string	Có	Địa chỉ TRON cần kích hoạt. Phải khớp với `^T[A-Za-z0-9]{33}$` (34 ký tự, bắt đầu bằng `T`).

Response — đã kích hoạt (200, mã `10000`)

json

{
    "detail": {
        "code": 10000,
        "msg": "Address activated successfully, 1.1 TRX deducted",
        "data": {
            "orderId": "A123456",
            "targetAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
            "activation_cost": 1.1,
            "user_balance_before": 500.00,
            "user_balance_after": 498.90,
            "hash": "0000000000000000000000000000000000000000000000000000000000000000"
        }
    }
}

Trường	Type	Description
`orderId`	string	Mã đơn hàng kích hoạt, luôn là `A` + các chữ số. Sử dụng mã này để đối soát.
`targetAddress`	string	Địa chỉ đã được kích hoạt
`activation_cost`	float	Số tiền bị trừ khỏi số dư của bạn, tính bằng TRX
`user_balance_before`	float	Số dư trước khi trừ
`user_balance_after`	float	Số dư sau khi trừ
`hash`	string	Mã băm giao dịch kích hoạt. Xác minh mã này trên bất kỳ trình khám phá TRON nào.

Response — đã hoạt động từ trước (200, mã `2001`)

Trả về khi địa chỉ đã tồn tại trên chuỗi. Không có khoản phí nào bị trừ.

json

{
    "detail": {
        "code": 2001,
        "msg": "Address is already activated",
        "data": {
            "targetAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
            "status": "already_activated",
            "user_balance": 500.00,
            "activation_cost": 0,
            "activation_required": false
        }
    }
}

Kiểm tra code trước khi cho rằng đã phát sinh phí: 10000 nghĩa là bạn đã thanh toán, 2001 nghĩa là bạn không bị trừ tiền.

Ví dụ

bash

curl -X POST https://netts.io/apiv2/activator \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key" \
  -d '{"targetAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"}'

Giá

Mục	Số tiền
Kích hoạt	1.1 TRX
Địa chỉ đã hoạt động	0

Số tiền này là cố định và không phụ thuộc vào địa chỉ hay điều kiện mạng lưới. Nó được trừ vào số dư Netts của bạn tại thời điểm kích hoạt thành công — không bao giờ trừ trước. Kích hoạt thất bại sẽ không tốn phí.

Số dư của bạn phải đủ để chi trả chi phí này, nếu không yêu cầu sẽ bị từ chối với mã 403 (1004) và không có đơn hàng nào được tạo.

Khi nào bạn cần điều này

Trước khi thuê năng lượng hoặc băng thông cho một địa chỉ mới. Việc ủy quyền cho một tài khoản chưa tồn tại sẽ thất bại. Hãy kích hoạt trước, sau đó mới đặt hàng.
Trước lần chuyển tiền đến đầu tiên tới một địa chỉ mà bạn tự tạo.

Bạn không cần gọi điểm cuối này cho một địa chỉ đã từng nhận TRX hoặc một token nào đó — địa chỉ này đã hoạt động rồi, và lệnh gọi sẽ chỉ đơn giản trả về 2001.

Đặt mua năng lượng cho một địa chỉ mới

Điểm cuối năng lượng 1 giờ sẽ tự kích hoạt một địa chỉ nhận chưa hoạt động như một phần của đơn hàng, và chi phí kích hoạt sẽ được cộng vào đơn hàng đó. Hãy gọi bộ kích hoạt một cách tường minh khi bạn muốn địa chỉ hoạt động trước bất kỳ giao dịch thuê nào — ví dụ như nạp thêm băng thông trước, điều vốn yêu cầu một tài khoản đã hoạt động.

Thời gian xử lý

Kích hoạt là một giao dịch thực tế trên chuỗi. Điểm cuối sẽ phản hồi sau khi giao dịch được phát đi và bản ghi kích hoạt được ghi lại, thường trong vòng vài giây.

Địa chỉ chỉ có thể sử dụng được sau khi giao dịch được đưa vào một khối (block) — tối đa khoảng ~3 giây sau phản hồi, vì đó là khoảng thời gian tạo khối của TRON. Nếu bước tiếp theo của bạn phụ thuộc vào việc địa chỉ đã hoạt động (chẳng hạn như đặt mua băng thông), hãy xác nhận trạng thái trên chuỗi bằng hash được trả về thay vì gọi ngay lập tức.

Tham chiếu mã lỗi

Mã	Description	Trạng thái HTTP
`10000`	Địa chỉ đã được kích hoạt, số dư đã bị trừ	200
`2001`	Địa chỉ đã được kích hoạt từ trước, không tính phí	200
`-1`	Khóa API không hợp lệ / IP không nằm trong danh sách trắng	401
`1004`	Không đủ tiền — thông báo sẽ nêu rõ số tiền cần thiết và số dư hiện có của bạn	403
`-`	Định dạng `targetAddress` không hợp lệ (phải gồm 34 ký tự, bắt đầu bằng `T`)	422
`5003`	Kích hoạt thất bại hoặc dịch vụ tạm thời không khả dụng — hãy thử lại sau	503
`5000`	Lỗi máy chủ nội bộ	500

Mã 503 có nghĩa là không có khoản phí nào bị trừ và chưa có địa chỉ nào được kích hoạt: bạn có thể thử lại yêu cầu một cách an toàn.

Giới hạn tốc độ

Giới hạn trên mỗi IP nguồn:

Khoảng thời gian	Giới hạn
1 giây	5 yêu cầu
1 phút	60 yêu cầu

Vượt quá giới hạn tần suất (429)

json

{ "message": "API rate limit exceeded" }

Tài khoản trả sau

Các tài khoản sử dụng thanh toán trả sau dùng chung điểm cuối, tiêu đề và thân yêu cầu. Điểm khác biệt là cách thức thanh toán chi phí kích hoạt:

Không có khoản tiền nào bị trừ khỏi khoản ký quỹ của bạn. Mỗi lần kích hoạt thành công sẽ được cộng vào số dư nợ trên tài khoản của bạn theo loại tiền tệ quyết toán được thỏa thuận trong hợp đồng. Bạn thanh toán số tiền này theo hóa đơn, theo thỏa thuận của bạn.
Tài khoản của bạn có một hạn mức tín dụng. Chừng nào số tiền đến hạn còn nằm trong hạn mức, các yêu cầu kích hoạt vẫn được chấp nhận ngay cả khi số tiền ký quỹ bằng không.
Chỉ những lần kích hoạt hoàn tất mới được lập hóa đơn. Một địa chỉ đã hoạt động từ trước (2001) và một lần kích hoạt thất bại sẽ không tốn phí.

Thanh toán trả sau được Netts kích hoạt cho tài khoản theo yêu cầu. Mỗi phản hồi đều cho bạn biết cách kích hoạt được thanh toán: paymentMode là postpaid hoặc prepaid.

Các trường yêu cầu bổ sung

Trường	Type	Required	Description
`test`	boolean	Không	`true` — chỉ tính toán giá và kiểm tra địa chỉ. Không có gì được kích hoạt hoặc lập hóa đơn
`freezePrice`	boolean	Không	`true` — cố định mức giá theo hợp đồng của bạn trong 60 giây. Không có gì được kích hoạt hoặc lập hóa đơn
`quoteId`	string	Không	Kích hoạt theo mức giá của báo giá được tạo bởi `freezePrice` cho cùng địa chỉ đó
`priceCurrency`	string	Không	`TRX` (mặc định) hoặc loại tiền tệ trong hợp đồng của bạn, như trong `settlement.asset`. Đối với tài khoản trả sau, số tiền theo loại tiền tệ trong hợp đồng của bạn luôn được bao gồm

quoteId không thể kết hợp với test hoặc freezePrice. Bất kỳ trường nào khác trong thân yêu cầu đều sẽ bị từ chối.

Kiểm tra giá (`test: true`)

json

{ "targetAddress": "TSMARToKjQGxroMnPKK6o6d4876VkQmHEH", "test": true }

json

{
    "detail": {
        "code": 10010,
        "msg": "Test calculation",
        "data": {
            "amount": 1,
            "unitPriceSun": null,
            "discount": null,
            "energyTRX": "0.000000",
            "activationTRX": "1.100000",
            "wouldCostTRX": "1.100000",
            "paidTRX": 0,
            "paymentMode": "postpaid",
            "activationCheck": "inactive",
            "alt": {"USDC": {"energy": "0.000000", "activation": "0.364333", "total": "0.364333"}},
            "fxAt": "2026-10-19T07:17:33.475335+00:00",
            "targetAddress": "TSMARToKjQGxroMnPKK6o6d4876VkQmHEH"
        }
    }
}

activationCheck: inactive — địa chỉ cần kích hoạt và sẽ bị tính phí; active — địa chỉ đã hoạt động, wouldCostTRX là 0; unknown — hiện tại không thể kiểm tra.

alt.<currency> — các số tiền tương đương theo loại tiền tệ trong hợp đồng của bạn. fxAt — thời điểm của tỷ giá hối đoái được áp dụng.

Báo giá cố định giá (`freezePrice: true`)

Gửi yêu cầu với "freezePrice": true. Phản hồi sẽ có mã 10011 (Quote issued), các trường tương tự như kiểm tra giá, kèm theo quoteId và expiresAt.
Trong vòng 60 giây, gửi yêu cầu với "quoteId": "<quoteId>" và cùng một targetAddress.
Việc kích hoạt sẽ được tính phí theo mức giá đã báo — mức giá theo hợp đồng của bạn tại thời điểm báo giá.

Báo giá chỉ có thể được sử dụng một lần. Báo giá đã hết hạn hoặc đã được sử dụng sẽ bị từ chối và không có gì được kích hoạt.

Kích hoạt thành công

json

{
    "detail": {
        "code": 10000,
        "msg": "Address activated successfully, 1.1 TRX service cost, postpaid",
        "data": {
            "orderId": "A564125",
            "targetAddress": "TSMARToKjQGxroMnPKK6o6d4876VkQmHEH",
            "activation_cost": 1.1,
            "user_balance_before": 0.0,
            "user_balance_after": 0.0,
            "hash": "bd9ea6ef92ce4ba6553af3930a03abe874cdfcc2399b7fdd9abdb11570de2920",
            "paymentMode": "postpaid",
            "activationTRX": "1.100000",
            "totalTRX": "1.100000"
        }
    }
}

Trường	Description
`activation_cost`	Chi phí kích hoạt tính bằng TRX. Đối với tài khoản trả sau, số tiền này không bị trừ vào khoản ký quỹ
`user_balance_before` / `user_balance_after`	Khoản ký quỹ của bạn — không thay đổi đối với tài khoản trả sau
`paymentMode`	`postpaid`
`activationTRX` / `totalTRX`	Số tiền chính xác, 6 chữ số thập phân
`quoteId`, `alt`	Xuất hiện khi việc kích hoạt được thực hiện cùng một báo giá

Đã đạt hạn mức tín dụng (402)

json

{
    "detail": {
        "code": 1004,
        "msg": "Postpaid credit limit reached.",
        "paymentMode": "postpaid",
        "reason": "limit_reached"
    }
}

Không có gì được kích hoạt và không có gì được lập hóa đơn. Các kích hoạt mới sẽ được chấp nhận trở lại sau khi khoản thanh toán của bạn được ghi nhận hoặc hạn mức của bạn được tăng lên.

Mã lỗi trả sau

Mã	HTTP	Description
`10010`	200	Kết quả kiểm tra giá (`test`)
`10011`	200	Báo giá đã được phát hành (`freezePrice`)
`1004`	402	Đã đạt hạn mức tín dụng trả sau
`4100`	400	Yêu cầu không hợp lệ
`4101`	400	`priceCurrency` không được hỗ trợ
`4102`	400	`quoteId` kết hợp với `test` hoặc `freezePrice`
`4103`	409	Báo giá đã được sử dụng
`4104`	409	Báo giá đã hết hạn
`4106`	404	Không tìm thấy báo giá
`4107`	409	Các tham số yêu cầu khác biệt so với báo giá
`4108`	400	Định dạng `quoteId` không hợp lệ
`4109`	422	Không khả dụng cho các tài khoản phụ
`5032`	503	Giá tạm thời không khả dụng
`5033`	503	Tỷ giá hối đoái tạm thời không khả dụng
`5034`	503	Tính phí tạm thời không khả dụng — yêu cầu kích hoạt không được chấp nhận
`5036`	503	Kiểm tra tín dụng tạm thời không khả dụng — hãy thử lại sau

Đối với tất cả các phản hồi 4xx và 503 ở trên, không có gì được kích hoạt và không có gì được lập hóa đơn.

Ghi chú

Tính lũy đẳng phụ thuộc vào bạn. Điểm cuối này không có khóa lũy đẳng (idempotency key). Việc gửi lại yêu cầu cho một địa chỉ đã hoạt động là an toàn và miễn phí (2001), nhưng hai yêu cầu đồng thời cho cùng một địa chỉ hoàn toàn mới có thể đều được xử lý tiếp. Hãy tuần tự hóa việc kích hoạt cho từng địa chỉ ở phía bạn.
Định dạng orderId là A + các chữ số và là duy nhất giữa các lần kích hoạt.
Hiện chưa có webhook nào được gửi cho thao tác kích hoạt — phản hồi và hash chính là xác nhận. Các webhook hiện chỉ bao gồm các ủy quyền năng lượng đã được xác nhận, xem Webhooks.

Bộ kích hoạt — kích hoạt địa chỉ ​

URL cơ sở của Endpoint ​

Headers của yêu cầu ​

Kích hoạt — POST /apiv2/activator ​

Body của yêu cầu ​

Response — đã kích hoạt (200, mã 10000) ​

Response — đã hoạt động từ trước (200, mã 2001) ​

Ví dụ ​

Giá ​

Khi nào bạn cần điều này ​

Thời gian xử lý ​

Tham chiếu mã lỗi ​

Giới hạn tốc độ ​

Vượt quá giới hạn tần suất (429) ​

Tài khoản trả sau ​

Các trường yêu cầu bổ sung ​

Kiểm tra giá (test: true) ​

Báo giá cố định giá (freezePrice: true) ​

Kích hoạt thành công ​

Đã đạt hạn mức tín dụng (402) ​

Mã lỗi trả sau ​

Ghi chú ​

Bộ kích hoạt — kích hoạt địa chỉ

URL cơ sở của Endpoint

Headers của yêu cầu

Kích hoạt — `POST /apiv2/activator`

Body của yêu cầu

Response — đã kích hoạt (200, mã `10000`)

Response — đã hoạt động từ trước (200, mã `2001`)

Ví dụ

Giá

Khi nào bạn cần điều này

Thời gian xử lý

Tham chiếu mã lỗi

Giới hạn tốc độ

Vượt quá giới hạn tần suất (429)

Tài khoản trả sau

Các trường yêu cầu bổ sung

Kiểm tra giá (`test: true`)

Báo giá cố định giá (`freezePrice: true`)

Kích hoạt thành công

Đã đạt hạn mức tín dụng (402)

Mã lỗi trả sau

Ghi chú