Skip to main content

Endpoints

1.Subscribe

watch-bus subscribes to the provider for the address to be monitored

Method: POST

URL: https://<domain>/api/watch/subscribe

Request body

NameRequiredTypeDescriptionExample
entity_listYesList<EntityInfo>List of addresses that need to be monitored

EntityInfo:

NameRequiredTypeDescriptionExample
entityYesstringcode of an event that should be monitored0x9bd547446ea13c0c13df2c1885e1f5b019a77441
chain_idYesintchain id56
entity_typeYesstringwatch entity typeERC20,ERC721,ERC777,ERC1155,ERC4626,Universal,Unverified
event_codeYesstringcode of an event that should be monitored. see here Specificationbig_amount_txn
[
{
"entity": "0x225982667df43a03922c5f64ccd3b24a00782ec3",
"chain_id": "56",
"entity_type": "ERC20",
"event_code": "big_amount_txn"
},

{
"entity": "0xe9e7CEA3DedcA5984780Bafc599bD69ADd087D56",
"chain_id": "56",
"entity_type": "ERC20",
"event_code": "big_amount_txn"
}
]

Response

NameNotNullTypeDescriptionExample
statusYesstringResult of operationOK:The scanning process terminated as expected

ERROR:Exception thrown or unexpected situation met
codeYesintResult code of operation000000000: success

000001: unknown server error occurred during detection

000002: Number of requests exceeded limit

000003: unknown appId

000004: X-Signature-signature header can't be null

000005: verify signature error

  • appid, timestamp, nonce, signature headers can not be null or empty
  • nonce is illegal
  • timestamp has illegal
  • timestamp is expired
  • invalid appid
  • appid has expired
  • invalid signature
  • replay request
  • app is out of count limit
dataYesjsonQuery resultSee Data form

Data:

NameNotNullTypeDescriptionExample
watch_resultYesList<EntityInfo>return success watch_entity (address)

EntityInfo:

NameRequiredTypeDescriptionExample
entityYesstringcode of an event that should be monitored0x9bd547446ea13c0c13df2c1885e1f5b019a77441
chain_idYesintchain id56
entity_typeYesstringwatch entity typeERC20,ERC721,ERC777,ERC1155,ERC4626,Universal,Unverified
event_codeYesstringcode of an event that should be monitored.big_amount_txn
{
"code": "000000000",
"status": "OK",
"data": {
"watch_result": [{
"entity": "0x225982667df43a03922c5f64ccd3b24a00782ec3",
"chain_id": "56",
"entity_type": "ERC20",
"event_code": "big_amount_txn"
},
{
"entity": "0xe9e7CEA3DedcA5984780Bafc599bD69ADd087D56",
"chain_id": "56",
"entity_type": "ERC20",
"event_code": "big_amount_txn"
}
]
}
}

2.Unsubscribe

watch-bus unsubscribes from provider

Method: POST

URL: https://<domain>/api/v1/watch/unsubscribe

Request body

NameRequiredTypeDescriptionExample
entity_listYesList<EntityInfo>List of addresses that need to be monitored

Response

NameNotNullDescriptionTypeExample
statusYesResult of operationstringOK:The scanning process terminated as expected

ERROR:Exception thrown or unexpected situation met
codeYesResult code of operationint000000000: success
dataYesQuery ResultjsonSee Data form

Data:

NameNotNullTypeDescriptionExample
watch_resultYesList<EntityInfo>return success watch_entity (address)

3.List subscriptions

watch-bus requests the subscribed address information from the provider

Method: POST

URL: https://<domain>/api/watch/subscriptions/list

Request body

NameRequiredTypeDescriptionExample
entity_listNoList<String>List of addresses that need to be monitored; entity_list is allowed to be empty, when entity_list=empty, all subscribed address information needs to be returned[“0x9bd547446ea13c0c13df2c1885e1f5b019a77441”, “0x8315177ab297ba92a06054ce80a67ed4dbd7ed3a”]
page_indexNoIntegerWhen the number is large, it will be processed by paging, and the page number needs to be set.Defaults 1
page_sizeNoIntegerWhen the number is large, it will be processed by paging, and the page number needs to be set.Defaults 50, max 50

Response

NameNotNullDescriptionTypeExample
statusYesResult of operationstringOK:The scanning process terminated as expected

ERROR:Exception thrown or unexpected situation met
codeYesResult code of operationint
dataYesQuery ResultjsonSee Data form

Data:

NameNotNullTypeDescriptionExample
subscription_listYesList<Subscription>Whether a result of subscription is true or falseSee “Subscription” form
page_indexYesIntegercurrent page number1
page_sizeYesIntegerpage size50
totalYesIntegertotal number of records10

Subscription:

NameNotNullTypeDescriptionExample
watch_entityYesStringaddresses that was monitored0x9bd547446ea13c0c13df2c1885e1f5b019a77441
watch_event_listYesList<WatchEvent>

WatchEvent:

NameNotNullTypeDescriptionExample
watch_idYesStringId of an event which is monitored, refers to a specific subscription object, expect to use watch_id to query all relevant information of a certain subscription, such as the creation time of the subscription, the address of the subscription ,etc.123
event_codeYesStringcode of an event that should be monitoredbig_amount_txn

4. Watch Events

Get the list of events supported by the provider

Method: POST

URL: https://<domain>/api/watch/event/list

Request body

empty

Response

NameNotNullDescriptionTypeExample
statusYesResult of operationstringOK:The scanning process terminated as expected

ERROR:Exception thrown or unexpected situation met
codeYesResult code of operationint
dataYesQuery ResultList<SupportEvent>See SupportEvent form

SupportEvent:

NameNotNullDescriptionTypeExample
event_codeYesstringcode of an event that should be monitoredbig_amount_txn
support_entity_type_listYesJSON List<String>watch entity type["EOA","ERC20","ERC721","ERC1155","UNIVERSAL"] UNIVERSAL: no ERC CA , Dapp
mini_thresholdYesstringMinimum threshold to trigger an alarm0.005
trigger_frequencyNostringNotification timeliness, when an event occurs, how soon can the watch-bus be notified, such as within 1 minute after the event occurs, or within 1 hourMinutes (blocks)
event_descriptionNostringevent descriptionlarge amount transfers

5.Alert (provider callback watch-bus, recommend to use ws protocol)

Provider sends real-time alarm information to watch-bus

Method: POST websocket will be used for integration.

URL: https://www.avengerdao.org/api/v1/watch/alert (provided by watch bus)

Authorization: reference Authorization

Request body

NameRequiredTypeDescriptionExample
alert_info_listYesList<AlertInfo>List of alert

AlertInfo:

NameRequiredTypeDescriptionExample
watch_entityYesstringcode of an event that should be monitored0x9bd547446ea13c0c13df2c1885e1f5b019a77441
chain_idYesStringchain id56
watch_entity_typeYesstringwatch entity typeERC20,ERC721,ERC777,ERC1155,ERC4626,Universal,Unverified
watch_event_codeYesstringcode of an event that should be monitoredbig_amount_txn
timestampYeslongTimestamp of the alarm, unix time, Second1678956256
event_valuesYesMapDetails of the eventsee EventValues Map

EventValues Map:

map format, the content of each event is different, here is an example of trust_score_decrease

NameRequiredTypeDescriptionExample
last_valueYesstringlast value95
last_tsYesstringlast value timestamp1665391590
current_valueYesstringcurruent value60
delta_valueYesstringdelta value greate than some value35
delta_percentYesstringdelta percent greate than some value0.3684
commentNostring
[
{
"chain_id": "56",
"watch_entity_type":"ERC20",
"address": "0x171C3688e1aB772e7178F19481dc8F8030F76fC9",
"timestamp": 1665395590,
"watch_event_code": "trust_score_decrease",
"event_values": {
"last_value": "95",
"last_ts": "1665391590",
"current_value": "60",
"delta_value": "35",
"delta_percent": "0.3684",
"comment": "some comments"
}
},

{
"chain_id": "56",
"watch_entity_type":"ERC20",
"address": "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c",
"timestamp": 1665395590,
"watch_event_code": "trust_score_decrease",
"event_values": {
"last_value": "99",
"last_ts": "1665391590",
"current_value": "98",
"delta_value": "1",
"delta_percent": "0.01",
"comment": "some comments"
}
}
]