Skip to content

Event Register

Create, modify or remove an event listener which can report server events via Event Wait. POST only.


  • requestType is eventRegister
  • event is one of multiple server events from the following list of event names: (optional, default is all possible events)
    • Block.BLOCK_POPPED
    • Block.BLOCK_PUSHED
    • Peer.ADD_INBOUND
    • Peer.BLACKLIST
    • Peer.NEW_PEER
    • Peer.REMOVE
  • event is one of multiple server events (optional)
  • add is true to add events to an existing listener (optional, omit if remove is true)
  • remove is true to remove events from an existing listener (optional, omit if add is true)
  • requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
  • requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Note: To create a new event listener, omit both add and remove. To remove an existing event listener, set remove to true and omit event; all registered events will be removed, any outstanding Event Wait will be completed and the listener will be deactivated.

Note: An event listener is automatically deactivated whenever all registered events are removed or if Event Wait is not called frequently enough, according to the xin.apiEventTimeout property. The timeout is not precise; the removal process runs every xin.apiEventTimeout / 2 seconds, so that many extra seconds may elapse before removal; the first Event Wait call should be made immediately after registration to avoid deactivation.

Note: Each API user (with a unique address) can create only one event listener. When a new one is created, it will replace an existing one. The maximum number of unique users is controlled by the xin.maxEventUsers property.


  • registered is true if the operation completed successfully
  • lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
  • requestProcessingTime (N) is the API request processing time (in millisec)