---

Crypto Payment Notification API

Real-time Cryptocurrency Incoming Payment Detection

---

Overview

Crypto Payment Notification API is a real-time blockchain monitoring service that detects incoming cryptocurrency payments to a specified wallet address within a defined time window.

The API verifies on-chain transactions and matches them based on blockchain network, asset type, address, amount, and time range, helping developers reliably confirm crypto payments and deposits.

---

Base URL

https://crypto-payment-notification-api.p.rapidapi.com

---

Endpoint

GET /v1/address/lookup

Detect incoming cryptocurrency payments for a specific wallet address.

---

Authentication

This API uses RapidAPI authentication.

Required Headers

Header Name	Description
x-rapidapi-key	Your RapidAPI subscription key
x-rapidapi-host	crypto-payment-notification-api.p.rapidapi.com
Accept	application/json

---

Query Parameters

Parameter	Type	Required	Example	Description
chain	string	✅	bitcoin	Blockchain network where the payment is made (e.g. bitcoin, ethereum, tron).
asset	string	✅	BTC	Cryptocurrency symbol to detect.
address	string	✅	1PuJjnF476W3zXfVYmJfGnouzFDAXakkL4	Destination wallet address to monitor for incoming payments.
amount	string	✅	3.14718398	Expected payment amount. Treated as string to avoid floating-point precision issues.
timestamp	integer	✅	1767943791	UNIX timestamp (seconds) representing the start of the payment detection window. Only transactions within this time window will be matched.

---

Timestamp & Time Window Rule

The timestamp parameter defines the start time of the payment window.

• The API only matches transactions whose block time falls within:

  timestamp  ~  timestamp + 1800 seconds (30 minutes)
  

• The timestamp should be generated before the user sends the payment.

• This mechanism prevents historical or duplicate transactions from being matched.

---

Example Request

curl --request GET \
  --url "https://crypto-payment-notification-api.p.rapidapi.com/v1/address/lookup?chain=bitcoin&amount=3.12947169&asset=BTC&timestamp=1767943791&address=1AfCc4F9c4VTYSE31PUe2kUEKs6ZxiDjxm" \
  --header "Accept: application/json" \
  --header "x-rapidapi-host: crypto-payment-notification-api.p.rapidapi.com" \
  --header "x-rapidapi-key: YOUR_RAPIDAPI_KEY"

---

Success Response

HTTP Status: 200 OK

{
  "code": 0,
  "message": "OK",
  "data": {
    "request": {
      "chain": "bitcoin",
      "asset": "BTC",
      "address": "1PuJjnF476W3zXfVYmJfGnouzFDAXakkL4",
      "amount": "3.14718398",
      "timestamp": 1767948041
    },
    "status": "failed",
    "matchedTx": {
      "txid": "8d693af40df1fd545481e3d93838e5a2400a07e1af9650aa5ccf79422a993e5f",
      "blockHeight": 931526,
      "blockTime": 1767948064,
      "from": null,
      "to": "1PuJjnF476W3zXfVYmJfGnouzFDAXakkL4",
      "amount": "3.14718398",
      "asset": "BTC"
    },
    "matchPolicy": {
      "direction": "in",
      "amountMatch": "exact",
      "timeWindowSec": 1800,
      "windowStart": 1767948041,
      "windowEnd": 1767949841,
      "requestId": "f3c81163-f021-4ee6-abf5-1bca112028df",
      "btcAmountUnit": "sats",
      "btcVoutField": "vout[].scriptpubkey_address & vout[].value"
    }
  }
}

---

Response Fields Explanation

status

Value	Meaning
success	A matching incoming payment was found
failed	No valid payment matched within the time window

---

matchedTx

Returned when a transaction is detected within the time window.

Field	Description
txid	Blockchain transaction hash
blockHeight	Block number containing the transaction
blockTime	Block timestamp (UNIX seconds)
from	Sender address (may be null for UTXO chains)
to	Destination address
amount	Transferred amount
asset	Asset symbol

---

matchPolicy

Describes the transaction matching rules used by the API.

Field	Description
direction	Transaction direction (in = incoming)
amountMatch	Amount matching strategy (exact)
timeWindowSec	Detection window duration (seconds)
windowStart	Window start timestamp
windowEnd	Window end timestamp
requestId	Unique request identifier
btcAmountUnit	BTC amount unit (sats)
btcVoutField	BTC output fields used for matching

---

Error Response

Time Window Expired

HTTP Status: 200 OK Error Code: 4100

{
  "code": 4100,
  "message": "error",
  "error": {
    "message": "time window expired",
    "requestId": "46af292a-188d-42b1-8dda-0987184ff098",
    "now": 1767948942,
    "windowStart": 1767943791,
    "windowEnd": 1767945591,
    "windowSec": 1800,
    "hint": "timestamp 已过期（超过窗口），请重新生成订单 timestamp"
  }
}

---

Error Codes

Code	Description
0	Success
4100	Time window expired
4xxx	Invalid request parameters
5xxx	Internal server error

---

Notes

• This API is read-only and does not require private keys.
• No custody or transfer of user funds is involved.
• For each payment attempt, a new timestamp should be generated.

---

Supported Assets

• BTC (Bitcoin)
• ETH (Ethereum)
• USDT (ERC20 / TRC20)
• TRX (TRON)
• DOGE (Dogecoin)

---