Poll API

Poll API provides a stream of Doma Protocol events. These events could be used to build your own representation of Doma protocol state, analytics, or any kind of processing.

API works using Poll -> Acknowledge system. It means that to receive new events, older events should be acknowledged. Sample integration could look like this:

  1. Call Poll API to get new events. Optional limit and eventTypes could be specified.

  2. Process events (store in database, send to message queue, etc.).

  3. Call Poll Ack API to acknowledge last received event (you can use lastId from response). This would acknowledge all of the events from polled batch.

Tips:

  • To process events one-by-one, specify limit=1 in Poll API call.

  • To reprocess already received events (e.g. if new event type is added), Poll Reset API can be used to rewind polling cursor to a lower id. To reset cursor to the beginning, eventId should be set to 0.

  • Each returned event has a uniqueId field, that can be used as an idempotency key for events processing.

Poll for new Doma Protocol events

get
/v1/poll

Returns blockchain events that have occurred since the last acknowledged event.

Authorizations
Api-KeystringRequired
Query parameters
cursorany · max: 255Optional

Cursor identifier to use for tracking the polling state. Can be used to manage multiple independent polling states.

limitany · min: 1Optional

Maximum number of events to return in a single response page.

finalizedOnlybooleanOptional

Whether to return only finalized events.

Default: true
Responses
200Success
application/json
get
/v1/poll
GET /v1/poll HTTP/1.1
Host: api-testnet.doma.xyz
Api-Key: YOUR_API_KEY
Accept: */*

{
  "events": [
    {
      "id": 101,
      "name": "example.com",
      "tokenId": "109782310436602119473309635585647935844683647842954156419454133097053284015402",
      "type": "NAME_TOKEN_MINTED",
      "uniqueId": "text",
      "relayId": "text",
      "eventData": {
        "networkId": "eip155:1",
        "finalized": true,
        "txHash": "text",
        "blockNumber": "11111",
        "logIndex": 1,
        "tokenAddress": "0x1234567890123456789012345678901234567890",
        "tokenId": "1",
        "type": "NAME_TOKEN_MINTED",
        "owner": "text",
        "name": "example.com",
        "expiresAt": "2026-01-17T13:55:54.099Z",
        "correlationId": "text"
      }
    }
  ],
  "lastId": 42,
  "hasMoreEvents": true
}

Acknowledge received events

post
/v1/poll/ack/{lastEventId}

Updates the last acknowledged event id for the client.

Authorizations
Api-KeystringRequired
Path parameters
lastEventIdintegerOptional

Last event id that was processed by the client.

Query parameters
cursorany · max: 255Optional

Cursor identifier to use for tracking the polling state. Can be used to manage multiple independent polling states.

Responses
200Success
No content
post
/v1/poll/ack/{lastEventId}
POST /v1/poll/ack/{lastEventId} HTTP/1.1
Host: api-testnet.doma.xyz
Api-Key: YOUR_API_KEY
Accept: */*

No content

Reset last acknowledged event

post
/v1/poll/reset/{eventId}

Updates the last acknowledged event id for the client. Can be used to reset the polling state to re-consume events.

Authorizations
Api-KeystringRequired
Path parameters
eventIdintegerOptional

Event id to reset the last acknowledged event id to.

Query parameters
cursorany · max: 255Optional

Cursor identifier to use for tracking the polling state. Can be used to manage multiple independent polling states.

Responses
200Success
No content
post
/v1/poll/reset/{eventId}
POST /v1/poll/reset/{eventId} HTTP/1.1
Host: api-testnet.doma.xyz
Api-Key: YOUR_API_KEY
Accept: */*

No content
PreviousDoma Multi-Chain SubgraphNextOrderbook API

Last updated