Transaction Result Notifications

Application Scenarios

After NFT/Token/Sats transfers are completed, if the sender or receiver of the transaction involves a Lightning Network address set by the application on the platform, the platform will notify the application through the callback interface set by the application on the platform, facilitating the application to keep track of related transactions in a timely manner.

Interface Link

The callback interface link is set through the platform. If the link is inaccessible, the application will not receive notifications. The notification URL must be directly accessible without parameters. Public domain names must use HTTPS. Example: notify_url: "https://domain.com/dapp/callback"

Notification Request Header Parameters

Parameter Name	Parameter Type	Parameter Description	Required	Remarks
API-Key	string	Application's apiKey	Yes	Application's apiKey
Timestamp	string	Timestamp	Yes	Timestamp in Unix seconds, e.g., 1763373188
Nonce	string	Random number	Yes	Random string, minimum 16 characters, maximum 32 characters
Sign	string	Signature	Yes	Signature used to verify the integrity and source of the message

Notification Request Body Parameters

Parameter Name	Parameter Type	Parameter Description	Required	Remarks
txType	string	Transaction type	Yes	Enum values: nft, token, sats
txId	long	Transaction ID	No	Transaction ID for nft and token
txHash	string	Transaction hash	No	Transaction hash for sats
outTradeNo	string	Out trade number	No	Out trade number for dapp
txAction	int	Transaction action	Yes	Enum values: 0 (send), 1 (receive)
txAddress	string	Transaction address	Yes	Transaction address

Examples

{
    "txType": "nft",
    "txId": 12,
    "outTradeNo": 20220308123456788,
    "txAction": 0,
    "txAddress": "bc1p5cyxnuxmeuwuvkwfem96lqzszd02n6xdcjrs20cac6yqjjwudpxqkedrcr@bitboom.fun"
}

{
    "txType": "sats",
    "txHash": "2496cd48daeb7c2497c2d108f1775b2460fb8b88a497bdaee5db51b9a28c7270",
    "outTradeNo": 20220308123456788,
    "txAction": 0,
    "txAddress": "bc1p5cyxnuxmeuwuvkwfem96lqzszd02n6xdcjrs20cac6yqjjwudpxqkedrcr@bitboom.fun"
}

Notification Request Response Parameters

Parameter Name	Parameter Type	Parameter Description	Required	Remarks
code	string	HTTP status code	Yes	Standard HTTP status code, 200 indicates success
message	string	Response message	Yes	Response description message
data	object	Response data	Yes	Contains business-level response information
data.code	string	Business status code	Yes	SUCCESS/FAIL, SUCCESS indicates the application successfully received and verified the notification
data.message	string	Business error message	No	Error reason when data.code is FAIL, e.g., signature failure, parameter format validation error, etc.

Example

Success Response

{
    "code": "200",
    "message": "请求成功",
    "data": {"code": "SUCCESS"}
}

Failure Response

{
    "code": "200",
    "message": "请求成功",
    "data": {"code": "FAIL", "message": "signature failure"}
}

Note: Even when business processing fails (data.code = "FAIL"), the HTTP status code remains "200" to indicate the request was received successfully. The actual business result is determined by the data.code field.

Callback Notifications