Tag Address Usage Guide

1. Overview

Tag Address is used to categorize and manage wallet addresses. When creating a payment order, merchants can specify tagName so the system automatically assigns a receiving address from the corresponding tagged address pool.

Address allocation rules:

• If an available address exists under the tag, the system prioritizes reusing it.
• If all addresses under the tag are occupied, the system automatically creates a new address.
• The newly created address is automatically assigned to the same tag.

This mechanism helps merchants achieve:

• Address categorization
• Address reuse
• Automatic address expansion

This mechanism is ideal for merchant scenarios that require managing a large number of receiving addresses.

2. End-to-End Workflow

The overall process is as follows:

3. Create a Tag

Documentation: Create Tag API

Before creating payment orders, merchants must create a tag first.

Endpoint:

POST /api/mer/user/tag

Request example:

{
  "tagName": "A1"
}

This example creates tag A1.

After successful creation, this tag can be referenced in payment orders.

4. Create a Payment Order

When creating an order, include tagName in the request parameters to specify which tagged address group should be used.

Endpoint:

POST /api/mer/payment/createPaymentOrder

Request example:

{
  "chainId": 136,
  "description": "A sample order",
  "isLegalTender": 0,
  "notifyUrl": "https://www.payment.com/api/notify",
  "outTradeNo": "C3",
  "quoteAmount": "0.01",
  "quoteCurrencySymbol": "USDT",
  "redirectionUrl": "https://www.payment.com/result?order=202312131805041280413",
  "tagName": "A1"
}

Parameters

Parameter	Description
chainId	Blockchain network ID
description	Order description
isLegalTender	Whether the order is a fiat order
notifyUrl	Callback URL used after successful payment
outTradeNo	Merchant order number
quoteAmount	Payment amount
quoteCurrencySymbol	Payment currency
redirectionUrl	Redirect URL after payment completion
tagName	Tag name used for address categorization

5. Address Allocation Rules

After an order is successfully created, the system runs the following logic:

1. Read tagName from the order
2. Query the address pool under that tag
3. Check whether any available address exists

Processing logic:

• If an available address exists, reuse an existing address first.
• If all addresses are occupied, create a new address automatically.

Address allocation decision flow:

Example (A1 tag address pool):

Address1
Address2
Address3
Address4
Address5

Address allocation results:

• Order1 -> Address1
• Order2 -> Address2
• Order3 -> Address3

If all addresses are occupied, the system automatically creates a new address (for example, Address6) and adds it to the A1 tag address pool.

6. Reassign Address Tag

Documentation: Update Wallet Tag API

If you need to change the tag assigned to an address, use the API below.

1. Query Address List

Endpoint:

GET /api/mer/user/list

The response includes:

• walletId
• tagId
• address

2. Update Address Tag

Endpoint:

POST /api/mer/user/wallet/tag

Request example:

{
  "walletId": "123456",
  "tagId": "A1"
}

After a successful update, the address is assigned to the new tag.

7. Complete Process Example

The complete workflow example is as follows: