Create a Deposit Address — createAddress

Creates (or retrieves) an on-chain deposit address for a merchant order. Once the user transfers funds to this address, the platform confirms the deposit and notifies you via the deposit callback.

POST https://api.anonypay.io/api/merchant/createAddress

• The request body is the business JSON encrypted with RSA-OAEP and Base64-encoded, and must be sent with the full set of signature headers ANONY-APP-ID / ANONY-TOKEN / ANONY-TIMESTAMP / ANONY-NONCE / ANONY-SIGN. See the protocol specification for details.
• Obtain ANONY-TOKEN via getToken.
• Every response has the shape { "code": 10000, "data": "<encrypted ciphertext>", "message": "success" }. Verify the signature on data, then decrypt it. Any code != 10000 means failure, with the reason in message.

USDC deposits on TRON are closed

Use trx addresses only for receiving TRX / TRC20-USDT. USDC deposits on the TRON chain have been closed: TRON-USDC sent to a trx address will not be credited and will not trigger a callback, and the funds cannot be booked automatically. Do not direct users to send USDC to a trx address.

Request Parameters

Field	Type	Required	Description
userOrder	string	Yes	Merchant order ID (unique; repeated calls return the same address)
addressType	string	Yes	Address type, see the enum below
callbackUrl	string	No	Callback URL for this address; falls back to the merchant's default callback URL if omitted

addressType enum

Value	Chain	Description
trx	TRON	Receives TRX / TRC20-USDT (USDC deposits are closed, see the warning above)
btc	Bitcoin	Reserved / coming soon; do not expose in production checkout until announced
solana	Solana	Receives SOL / SPL assets (USDT, USDC)
eth_bnb	Ethereum + BSC	A single address receives assets on both the ETH and BSC chains
ton	TON	Receives TON / TON-USDT

Supported deposit currency symbols (the currency value in callbacks and query endpoints): trx trx.usdt eth eth.usdt eth.usdc solana solana.usdt solana.usdc bnb bnb.usdt bnb.usdc ton ton.usdt.

Response Fields (after decryption)

Field	Type	Description
address	string	Deposit address
apiOrder	string	Platform order ID
addressDatas	array	Reserved for multi-address chains; currently usually null

Sample response JSON (the content of data after signature verification and decryption):

{
  "address": "T*********************************",
  "addressDatas": null,
  "apiOrder": "order ID generated by the platform"
}

Idempotency and implementation notes

• The idempotency key is (userOrder, merchant ID): calling again with the same userOrder does not create a new address — the original one is returned. If the repeated call carries a callbackUrl different from the stored one, the platform updates the address's callback URL to the new value.
• callbackUrl goes through an SSRF check: private-network / loopback and other illegal addresses are rejected with invalidCallbackUrl. Provide a publicly reachable HTTPS URL.
• Addresses come from a platform-managed address pool: if the pool for the target chain is temporarily out of stock, the call fails with createAddressFailed. This is a platform-side issue unrelated to your request — retry later, and contact the platform if it persists.
• An eth_bnb address receives both ETH and BSC assets: there is no need to create separate addresses per chain; use currency in the callback to distinguish the actual asset.
• ton addresses are converted to raw format before chain scanning: when reconciling, keep in mind that a TON address has multiple equivalent representations — do not compare different formats of the same address by exact string equality.

Code Examples

PHP

require 'AnonyV2Client.php';
$client = new AnonyV2Client($appId, $serverPublicKeyB64, $merchantPrivateKeyB64);
$token  = $client->getToken($secret);  // handles md5 auth + signature verification/decryption, returns the token
$res = $client->post('createAddress', ['userOrder'=>'A1001','addressType'=>'trx'], $token);
// $res['data'] is already verified + decrypted: { address, addressDatas, apiOrder }

Python

from anony_v2 import AnonyV2Client
import requests

c = AnonyV2Client(app_id, server_pub_b64, merchant_priv_b64)

req = c.build_request({"userOrder": "A1001", "addressType": "trx"}, token)
r = requests.post(c.base_url + "createAddress", data=req["body"], headers=req["headers"])
body = r.json()
if body["code"] == 10000:
    data = c.verify_response(body["data"], r.headers["ANONY-TIMESTAMP"],
                             r.headers["ANONY-NONCE"], r.headers["ANONY-SIGN"])
    # data = { address, addressDatas, apiOrder }

Node.js

const { AnonyV2Client } = require('./anony_v2');
const c = new AnonyV2Client(appId, serverPubB64, merchantPrivB64);
const token = await c.getToken(secret); // Node ≥18
const req = c.buildRequest({ userOrder: 'A1001', addressType: 'trx' }, token);
const r = await fetch(c.baseUrl + 'createAddress', { method: 'POST', body: req.body, headers: req.headers });
const body = await r.json();
if (body.code === 10000) {
  const data = c.verifyResponse(body.data, r.headers.get('anony-timestamp'),
    r.headers.get('anony-nonce'), r.headers.get('anony-sign'));
  // data = { address, addressDatas, apiOrder }
}

See the SDK overview for how to obtain and initialize the SDK in each language.

Related Error Codes

On failure the outer code = 9999 and message is one of the following (see error codes for the full list):

message	Description	What to do
paramError	Invalid parameters (missing required field, wrong format, body too long, etc.)	Check that userOrder / addressType are sent as described on this page
invalidCallbackUrl	Illegal callback URL (failed the SSRF check, e.g. a private-network address)	Use a publicly reachable callback URL
addressTypeError	addressType is not currently open	Use trx / solana / eth_bnb / ton; btc is reserved until Bitcoin deposits are announced
createAddressFailed	Address pool out of stock, creation failed	Platform-side issue — retry later; contact the platform if it persists

Signature/authentication errors (signatureFailed / tokenExpired, etc.) are protocol-level issues unrelated to this endpoint — see the troubleshooting guide.

Next Steps

• How the platform notifies you once an address receives a deposit: Callbacks
• Query deposit records proactively: getDeposits
• Generate a payment QR code for an address (plaintext public endpoint): Public endpoints