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-Key

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.

includeSyntheticsbooleanOptional

Whether to include synthetic token events.

Default: false

finalizedOnlybooleanOptional

Whether to return only finalized events.

Default: true

Responses

200Success

application/json

400

Bad Request. Invalid query parameters.

401

Unauthorized. API Key is missing or invalid.

403

Forbidden. API Key is missing 'EVENTS' permission.

get

/v1/poll

HTTPcURLJavaScriptPython

GET /v1/poll HTTP/1.1
Api-Key: YOUR_API_KEY
Accept: */*

{
  "events": [
    {
      "id": 101,
      "name": "example.com",
      "eoi": false,
      "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",
        "registrarIanaId": 1345,
        "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-Key

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

400

Bad Request. Invalid event id.

401

Unauthorized. API Key is missing or invalid.

403

Forbidden. API Key is missing 'EVENTS' permission.

post

/v1/poll/ack/{lastEventId}

HTTPcURLJavaScriptPython

POST /v1/poll/ack/{lastEventId} HTTP/1.1
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-Key

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

400

Bad Request. Invalid event id.

401

Unauthorized. API Key is missing or invalid.

403

Forbidden. API Key is missing 'EVENTS' permission.

post

/v1/poll/reset/{eventId}

HTTPcURLJavaScriptPython

POST /v1/poll/reset/{eventId} HTTP/1.1
Api-Key: YOUR_API_KEY
Accept: */*

No content