Blocks

Blocks are what make up the Mainsail blockchain. These contain transactions that define the state of the chain. On this page, we give an overview of the various endpoints you can use to query Block data from the API.

It is not possible to POST a block through the public API. Nodes only accept blocks posted by a validator at the correct time through the internal API.

Properties

Name
hash
Type
string
Description
Unique identifier for the block.
Name
number
Type
integer
Description
The height of the block.
Name
timestamp
Type
string
Description
The timestamp when the block was created.
Name
transactionsCount
Type
integer
Description
The number of transactions included in the block.
Name
confirmations
Type
integer
Description
The number of confirmations the block has.
Name
generator
Type
string
Description
The public key of the block generator.
Name
forged
Type
object
Description
The details of the block's forged values, including amount, fee, reward, and total.
Name
previous
Type
string
Description
The identifier of the previous block.
Name
signature
Type
string
Description
The cryptographic signature of the block.
Name
payload
Type
object
Description
The payload of the block, including the hash and length.
Name
version
Type
integer
Description
The version of the block.

GET/blocks

List All Blocks

The Public API may be used to query for blocks. This dataset contains millions of blocks; thus for analytical purposes, we recommend you query the database directly.

Query Parameters

Name
page
Type
integer
Description
The number of the page that will be returned.
Name
limit
Type
integer
Description
The number of resources per page.
Name
offset
Type
integer
Description
The number of resources to be skipped.
Name
transform
Type
boolean
Description
Whether to transform the response structure.
Name
orderBy
Type
string
Description
The column and order by which the resources will be sorted.
Name
id
Type
string
Description
The identifier of the block to be retrieved.
Name
number
Type
integer
Description
The height of the block to be retrieved.
Name
height.from
Type
integer
Description
The height from which blocks will be retrieved.
Name
height.to
Type
integer
Description
The height to which blocks will be retrieved.
Name
timestamp
Type
integer
Description
The timestamp of the block to be retrieved.
Name
timestamp.from
Type
integer
Description
The timestamp from which blocks will be retrieved.
Name
timestamp.to
Type
integer
Description
The timestamp to which blocks will be retrieved.

Request

GET

/blocks?page=1&limit=5

curl -G https://testnet.mainsailhq.com/api/blocks \
  -d page=1 \
  -d limit=5

Response

{
  "meta":{
      "totalCountIsEstimate":true,
      "count":5,
      "first":"/blocks?orderBy=height%3Adesc&transform=true&limit=5&page=1",
      "last":"/blocks?orderBy=height%3Adesc&transform=true&limit=5&page=12482",
      "next":"/blocks?orderBy=height%3Adesc&transform=true&limit=5&page=2",
      "pageCount":12482,
      "previous":null,
      "self":"/blocks?orderBy=height%3Adesc&transform=true&limit=5&page=1",
      "totalCount":25982
  },
  "data":[
      {
        "confirmations":0,
        "amount":"0",
        "fee":"0",
        "reward":"0",
        "total":"0",
        "proposer":"0xFb0Af483A0a4FdE23EA71aDBE2ea2D4301828E4B",
        "publicKey":"03be3616815c3a5115c229279b9e2e0c755c9a105a973e7cba68921996c177057b",
        "username":"genesis_20",
        "number":62355,
        "hash":"9d5010fc7bd3064cb2e813f4c4fb0a6a493fa7f51b762452f9e7a8ab21f63362",
        "transactionsRoot":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
        "payloadSize":0,
        "parentHash":"fb2b4da669d12e33ea4e6c7a53e647ae95a4dbd015ffc09b855252c976c26e26",
        "signature":"b166e0a8c914ad174d37d59478ce6c289948208dd29e92e2059d9a10e9d102ba5138cfa84eec4ce2d5dbadfdec5c8e3f1272d2568f31ede2b806a5130c3b0df8c821853dc9490593d4e5065f33c77c99ba45bca5de58672f4dfa24ef86ba6160",
        "timestamp":"1725294954993",
        "transactionsCount":0,
        "version":1
      },
      {
        // ...
      },
      // ...
  ]
}

GET/blocks/first

Retrieve first block

Retrieves the very first block in the blockchain. This block represents the genesis of the blockchain, containing the initial set of transactions that started the chain.

Query Parameters

Name
transform
Type
boolean
Description
Whether to transform the response structure.

Request

GET

/blocks/first

curl https://testnet.mainsailhq.com/api/blocks/first

Response

{
  "data": {
    "confirmations": 64458,
    "amount": "124999999999999999999999959",
    "fee": "0",
    "reward": "0",
    "total": "0",
    "proposer": "0xdE983E8d323d045fde918B535eA43e1672a9B4ea",
    "publicKey": "033e78b697c509a3159c9a8b039e9cd349562f36b25a62056d8bbb5d3ab253efb1",
    "number": 0,
    "hash": "a95e5eab395803cccfb13459d15d79225ee9c5b4c6b257d0e0dacab7864b5c8b",
    "transactionsRoot": "23f7ed70542c797394f81c45b9afa3b076ffbb221fd3b7a7659f3a273ece0673",
    "payloadSize": 39529,
    "parentHash": "0000000000000000000000000000000000000000000000000000000000000000",
    "signature": "",
    "timestamp": "1724753709339",
    "transactionsCount": 212,
    "version": 1
  }
}

GET/blocks/last

Retrieve last block

Retrieves the most recent block in the blockchain. This block contains the latest set of transactions and updates the current state of the chain.

Query Parameters

Name
transform
Type
boolean
Description
Whether to transform the response structure.

Request

GET

/blocks/last

curl https://testnet.mainsailhq.com/api/blocks/last

Response

{
  "data": {
    "confirmations": 0,
    "amount": "0",
    "fee": "0",
    "reward": "0",
    "total": "0",
    "proposer": "0x38f3f308e63Ae213633d71ed6f4A89d4Ee7C386e",
    "publicKey": "02872e746de4310161781ce49eddfd9ec492a9cf3a9bf0c5571af7eb2e175c2d2c",
    "username": "genesis_37",
    "number": 64476,
    "hash": "b8200d472257343116445b6a35760aa1157bc04654f7f8f2bacd63d8b402c801",
    "transactionsRoot": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "payloadSize": 0,
    "parentHash": "ca5be66415a369827df7a9f23fa0c3681020be6391027401c5e0c18d4dd528bf",
    "signature": "80d49a41dedc7ec9978614b83be345ae8a912b0f59c92e14aeaf79658539ceff411749a56ae83d8a8cb2dbe28ed720a9134ae82aa89f2396a88e43691fff145b788e662afb7516cee709558bf276098541b5e28e88f056475540b4f932d93cfa",
    "timestamp": "1725312683090",
    "transactionsCount": 0,
    "version": 1
  }
}

GET/blocks/:id

Retrieve a block

Blocks may be retrieved by ID or by height. The height is an incremental integer.

Query Parameters

Name
transform
Type
boolean
Description
Whether to transform the response structure.

Request

GET

/blocks/:id

curl https://testnet.mainsailhq.com/api/blocks/827a1f88d621d0c83723df04bfddbb826049e9f2f465d5ec1e1e2ed280dba5da

Response

{
  "data": {
    "confirmations": 2,
    "amount": "0",
    "fee": "0",
    "reward": "0",
    "total": "0",
    "proposer": "0x6762BAAaE8374748793c77225FFb6a444a9D5de9",
    "publicKey": "02ab5bebf52333bdad0d3d75e6b5b1f602adf7b8af6faa87c23b2e121318f95542",
    "username": "genesis_26",
    "number": 64416,
    "hash": "827a1f88d621d0c83723df04bfddbb826049e9f2f465d5ec1e1e2ed280dba5da",
    "transactionsRoot": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "payloadSize": 0,
    "parentHash": "37b72ec9fa4a06104a23766f6693c476f464d3489efceee6522416081e43489c",
    "signature": "a915c149ef0552326dee7f4823ca4e0a2569a77a59ca818b0dc7fb7393453003a1f619973fadf9b8b00058243b889ae2018115834be159b0cfde6d7f3ccb4faa2801a7fc1a001a0402443b066019c3eb29e78051aabbab4facdc14ecdd837d1b",
    "timestamp": "1725312167763",
    "transactionsCount": 0,
    "version": 1
  }
}

GET/blocks/:id/transactions

List All Transactions in a Block

Instead of deserializing the block’s payload, you can also obtain the transactions of each block as proper transaction objects directly.

Query Parameters

Name
page
Type
integer
Description
The number of the page that will be returned.
Name
limit
Type
integer
Description
The number of resources per page.
Name
offset
Type
integer
Description
The number of resources to be skipped.
Name
transform
Type
boolean
Description
Whether to transform the response structure.
Name
orderBy
Type
string
Description
The column and order by which the transactions will be sorted.

Request

GET

/blocks/:id/transactions

curl -G https://testnet.mainsailhq.com/api/blocks/be1f1fd6383bf8db14ffe2f9eef78f5ee18a6835961a15502c85403377793b02/transactions \
  -d orderBy=timestamp:desc \
  -d limit=5

Response

{
  "meta": {
    "totalCountIsEstimate": true,
    "count": 1,
    "first": "/blocks/be1f1fd6383bf8db14ffe2f9eef78f5ee18a6835961a15502c85403377793b02/transactions?orderBy=timestamp%3Adesc&orderBy=sequence%3Adesc&transform=true&limit=5&page=1",
    "last": "/blocks/be1f1fd6383bf8db14ffe2f9eef78f5ee18a6835961a15502c85403377793b02/transactions?orderBy=timestamp%3Adesc&orderBy=sequence%3Adesc&transform=true&limit=5&page=1",
    "next": null,
    "pageCount": 1,
    "parentHash": null,
    "self": "/blocks/be1f1fd6383bf8db14ffe2f9eef78f5ee18a6835961a15502c85403377793b02/transactions?orderBy=timestamp%3Adesc&orderBy=sequence%3Adesc&transform=true&limit=5&page=1",
    "totalCount": 1
  },
  "data": [
    {
      "value": "100000000",
      "asset": null,
      "blockHash": "be1f1fd6383bf8db14ffe2f9eef78f5ee18a6835961a15502c85403377793b02",
      "confirmations": 3524,
      "fee": "10000000",
      "hash": "2afcc05f4ee56516647ceb1c3683a2b8cebf6f0ff36cd69bd8bf4c65038febd8",
      "nonce": "17",
      "recipient": "0xDC0A21aF27FeB1b7e0f2e519288445c0510Cb23C",
      "senderPublicKey": "025f81956d5826bad7d30daed2b5c8c98e72046c1ec8323da336445476183fb7ca",
      "signature": "1012a1c108348ff5591a4a2d5460e6b6bf0bd5fb048cb3fc26050c939d2cfad33d0a6591846afd7404916d185f9a0280c8328e841213f86de455fa5b998a1dbb",
      "signatures": null,
      "timestamp": "1725287126554",
      "type": 0,
      "typeGroup": 1,
      "vendorField": null,
      "version": 1
    }
  ]
}