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.

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

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

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

Authorizations

Query parameters

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

400

Bad Request. Invalid query parameters.

401

Unauthorized. API Key is missing or invalid.

403

Forbidden. API Key is missing 'EVENTS' permission.

get

HTTPcURLJavaScriptPython

GET /v1/poll HTTP/1.1
Host: api-testnet.doma.xyz
Api-Key: YOUR_API_KEY
Accept: */*

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

Acknowledge received events

post

Updates the last acknowledged event id for the client.

Authorizations

Path parameters

lastEventIdintegerOptional

Last event id that was processed by the client.

Responses

200Success

400

Bad Request. Invalid event id.

401

Unauthorized. API Key is missing or invalid.

403

Forbidden. API Key is missing 'EVENTS' permission.

post

HTTPcURLJavaScriptPython

POST /v1/poll/ack/{lastEventId} HTTP/1.1
Host: api-testnet.doma.xyz
Api-Key: YOUR_API_KEY
Accept: */*

No content