iotex-core - gRPC API - IoTeX Developer Documentation

When running in "Gateway" mode, an IoTeX node exposes both the IoTeX native API and the Ethereum JSON API. The IoTeX native API is based on the gRPC protocol. In this document, we list the official IoTeX public gateway nodes exposing the gRPC API and the API calls reference.
Official gRPC API endpoints
Mainnet
Endpoint
Provider
More
api.iotex.one:443
IoTeX Foundation
​https://iotex.io​
api.mainnet.iotex.one:443
IoTeX Foundation
​https://iotex.io​
Testnet
Endpoint
Text
More
api.testnet.iotex.one:443
IoTeX Foundation
​https://iotex.io​
gRPC API Reference
Below is the alphabetical list of all available gRPC calls provided by the IoTeX native API. To run the examples you can use the grpcurl command-line client for your OS.
If you are accessing a non-TLS endpoint, make sure you use -plaintext option in your grpcurl command.
EstimateActionGasConsumptionByExecution
1
Usage: 
2
Get Estimated Action Gas Consumption By Execution
3
Request: 
4
  Execution: iotextypes.Execution 
5
    -Amount: Execution Amount 
6
    -Contract: Contract Address 
7
    -Data: Data 
8
  CallerAddress: Address of Caller
9
​
10
Response: 
11
  Gas: Estimated Gas Amount
Copied!
Example:
1
➜  ~ grpcurl -d '{"execution": {"amount":"0", "contract":"io154mvzs09vkgn0hw6gg3ayzw5w39jzp47f8py9v"}, "callerAddress": "io1juvx5g063eu4ts832nukp4vgcwk2gnc5cu9ayd"}' api.mainnet.iotex.one:443 iotexapi.APIService.EstimateActionGasConsumption
2
​
3
{
4
  "gas": "10000"
5
}
Copied!
EstimateActionGasConsumptionByTransfer
1
Usage:
2
  Get Estimated Action Gas Consumption By Transfer
3
Request:
4
  Transfer: iotextypes.Transfer
5
    -Amount: Transfer Amount
6
    -Recipient: Recipient Address
7
    -Payload: Payload
8
  CallerAddress: Address of Caller
9
​
10
Response:
11
  Gas: Estimated Gas Amount

Copied!
Example:
1
➜  ~ grpcurl -d '{"transfer": {"amount":"100000", "recipient":"io1juvx5g063eu4ts832nukp4vgcwk2gnc5cu9ayd"}, "callerAddress": "io1juvx5g063eu4ts832nukp4vgcwk2gnc5cu9ayd"}'  api.mainnet.iotex.one:443 iotexapi.APIService.EstimateActionGasConsumption
2
​
3
{
4
  "gas": "10000"
5
}

Copied!
EstimateGasForAction
1
Usage:
2
  Get Estimated Gas For Action
3
Request:
4
  Action: Action
5
Response:
6
  Gas: Gas

Copied!
Example:
1
➜  ~ grpcurl -d '{"action": {"core": {"version": 1, "nonce": 2, "gasLimit": 10000, "gasPrice": "1000000000000", "execution": {"amount": "0", "contract": ""}}, "senderPubKey": "BOk7WxyPumkmNlKkg61VMY5O7VtRIjFMt/2wd9jHKVCXzsku5QsRCNx0lalyDlkh5W0wSON6vmpnFtfJuRPp8uY=", "signature": "9mrqFBggiRocZhkRVUswxs83NaEFNdEYYczI8049vlovHEP4YMQz+3Isznc3CrYaJxAbc2PTIz7y2meerJ8bHAA="}}' api.iotex.one:443 iotexapi.APIService.EstimateGasForAction
2
​
3
{
4
  "gas": 10000
5
}

Copied!
GetAccount
1
Usage:
2
  Get Account Details
3
Request:
4
  Address: Account Encoded Address
5
Response:
6
  AccountMeta: Account Metadata

Copied!
Example:
1
➜  ~ grpcurl -d '{"address": "io1juvx5g063eu4ts832nukp4vgcwk2gnc5cu9ayd"}' api.mainnet.iotex.one:443 iotexapi.APIService.GetAccount
2
​
3
{
4
  "accountMeta": {
5
    "address": "io1juvx5g063eu4ts832nukp4vgcwk2gnc5cu9ayd",
6
    "balance": "0",
7
    "nonce": "2",
8
    "pendingNonce": "3",
9
    "numActions": "2"
10
  }
11
}

Copied!
GetActionsByAddress
1
Usage:
2
  Get Actions By Address
3
Request:
4
  ByAddr: GetActionsByAddressRequest
5
    -Address: Encoded Address
6
    -Start: Start Index of Actions
7
    -Count: Number of Actions
8
Resposne:
9
  ActionInfo: List of Action Info

Copied!
Example:
1
➜  ~ grpcurl -d '{"byAddr": {"address": "io1juvx5g063eu4ts832nukp4vgcwk2gnc5cu9ayd", "start": 0, "count": 1}}' api.mainnet.iotex.one:443 iotexapi.APIService.GetActions
2
​
3
Resolved method descriptor:
4
rpc GetActions ( .iotexapi.GetActionsRequest ) returns ( .iotexapi.GetActionsResponse );
5
​
6
Request metadata to send:
7
(empty)
8
​
9
Response headers received:
10
content-type: application/grpc
11
​
12
Response contents:
13
{
14
  "actionInfo": [
15
    {
16
      "action": {
17
        "core": {
18
          "version": 1,
19
          "nonce": 1,
20
          "gasLimit": 10000,
21
          "gasPrice": "10000000000000",
22
          "transfer": {
23
            "amount": "1000000000000000000",
24
            "recipient": "io1sxm6zl56um2c3ntq5fwqjar4za5ka560x53muy"
25
          }
26
        },
27
        "senderPubKey": "BOk7WxyPumkmNlKkg61VMY5O7VtRIjFMt/2wd9jHKVCXzsku5QsRCNx0lalyDlkh5W0wSON6vmpnFtfJuRPp8uY=",
28
        "signature": "9mrqFBggiRocZhkRVUswxs83NaEFNdEYYczI8049vlovHEP4YMQz+3Isznc3CrYaJxAbc2PTIz7y2meerJ8bHAA="
29
      },
30
      "actHash": "060a93a4784469f9e587da0c90ed20df58b0effb50d6b8ddcd9a4c65ad55fcbd",
31
      "blkHash": "6344115bcd43b7315ffdf5338d0f97b26caed7734efea034a27208f64670f5e9",
32
      "timestamp": "2019-04-17T00:10:30.468419Z"
33
    }
34
  ]
35
}

Copied!
GetActionsByBlock
1
Usage:
2
  Get Actions By Block
3
Request:
4
  ByBlk: GetActionsByBlockRequest
5
    -BlkHash: Block Hash
6
    -Start: Start Index of Actions
7
    -Count: Number of Actions
8
Resposne:
9
  ActionInfo: List of ActionInfo

Copied!
Example:
1
➜  ~ grpcurl -d '{"byBlk": {"blkHash": "6344115bcd43b7315ffdf5338d0f97b26caed7734efea034a27208f64670f5e9", "start": 0, "count": 1}}' api.mainnet.iotex.one:443 iotexapi.APIService.GetActions
2
​
3
{
4
  "actionInfo": [
5
    {
6
      "action": {
7
        "core": {
8
          "version": 1,
9
          "gasPrice": "0",
10
          "grantReward": {
11
            "height": "1"
12
          }
13
        },
14
        "senderPubKey": "BGR5G9TOfUUQEoCJ+x262Gp+8wv/0/K73OZKl/P6tJEO+CVthBN9yiFyLZFejCeWoyy5WKy14B+iUAdGjPglhQg=",
15
        "signature": "fsCLFdClaIYAbwcyeUduhYOzvdncK412GqfEYQqxEwlZXMVfbrrOXVsRAmrtnz69J/t/Z+vlpeTfmqN4LkGt0gA="
16
      },
17
      "actHash": "dd2e83336f1ff219b1e54558f0627e1f556ed2caeedb44b758b0e107aa246531",
18
      "blkHash": "230ba8095d5a505e355652f9dcc2b13605419a8fa3d3fd5ddc6d24fd6a902641",
19
      "timestamp": "2019-04-22T02:06:30Z",
20
      "blkHeight": "1",
21
      "sender": "io1vtm2zgn830pn6auc2cvnchgwdaefa9gr4z0s86"
22
    }
23
  ],
24
  "total": "2"
25
}

Copied!
GetActionByHash
1
Usage:
2
  Get Action By Action Hash
3
Request:
4
  ByHash: GetActionByHashRequest
5
    -ActionHash: Hash of Action
6
    -CheckPending: Wether To Check Pending Actions in Action Pool
7
Response:
8
  ActionInfo: Action Info

Copied!
Example:
1
➜  ~ grpcurl -d '{"byHash": {"actionHash": "b7024bc52f315fafb9cc7677e730aec79767b28fbaa6bdd1f37c1861dd699aba", "checkPending": false}}' api.mainnet.iotex.one:443 iotexapi.APIService.GetActions
2
​
3
{
4
  "actionInfo": [
5
    {
6
      "action": {
7
        "core": {
8
          "version": 1,
9
          "gasLimit": "5000000",
10
          "gasPrice": "0",
11
          "transfer": {
12
            "amount": "0",
13
            "recipient": "io1vtm2zgn830pn6auc2cvnchgwdaefa9gr4z0s86",
14
            "payload": "cmNxZ2pzeGZkeHpzenp0cHlkemx6Y2xwbHo6Ly9VMkZzZEdWa1gxOUU0dzJRZ2dQSi82TjM4ZUNVNFlUdk9OeUs4QTVqWjFYSW9RREMybFpCSEdlOWRERmtONlRvSnFhQXhjUHg2SkV6T3YveWlWQWw2YStQeW0rSTAyQnZsZVcybWNLdU1WNnRXSFJIVG5KdXU5ODF4MlhQMm9XOQ=="
15
          }
16
        },
17
        "senderPubKey": "BGR5G9TOfUUQEoCJ+x262Gp+8wv/0/K73OZKl/P6tJEO+CVthBN9yiFyLZFejCeWoyy5WKy14B+iUAdGjPglhQg=",
18
        "signature": "aHHaBSzCb2pkAa6V/oqHruAkvjXHg6LH51LRJob8Cf1hAh6SxjVZlbCtVhVq0BCIJW9vf2Gd/gPLxa56kpZmhQE="
19
      },
20
      "actHash": "b7024bc52f315fafb9cc7677e730aec79767b28fbaa6bdd1f37c1861dd699aba",
21
      "blkHash": "230ba8095d5a505e355652f9dcc2b13605419a8fa3d3fd5ddc6d24fd6a902641",
22
      "timestamp": "2019-04-22T02:06:30Z",
23
      "blkHeight": "1",
24
      "sender": "io1vtm2zgn830pn6auc2cvnchgwdaefa9gr4z0s86",
25
      "gasFee": "0"
26
    }
27
  ],
28
  "total": "1"
29
}
Copied!
GetActionsByIndex
1
Usage:
2
  Get Actions By Index
3
Request:
4
  ByIndex: GetActionsByIndexRequest
5
    -Start: Start Index of Actions
6
    -Count: Number of Actions
7
Response:
8
  ActionInfo: List of Action Info

Copied!
Example:
1
➜  ~ grpcurl -d '{"byIndex": {"start": 0, "count": 2}}' api.mainnet.iotex.one:443 iotexapi.APIService.GetActions
2
​
3
{
4
  "actionInfo": [
5
    {
6
      "action": {
7
        "core": {
8
          "version": 1,
9
          "gasPrice": "0",
10
          "grantReward": {
11
            "height": "1"
12
          }
13
        },
14
        "senderPubKey": "BGR5G9TOfUUQEoCJ+x262Gp+8wv/0/K73OZKl/P6tJEO+CVthBN9yiFyLZFejCeWoyy5WKy14B+iUAdGjPglhQg=",
15
        "signature": "fsCLFdClaIYAbwcyeUduhYOzvdncK412GqfEYQqxEwlZXMVfbrrOXVsRAmrtnz69J/t/Z+vlpeTfmqN4LkGt0gA="
16
      },
17
      "actHash": "dd2e83336f1ff219b1e54558f0627e1f556ed2caeedb44b758b0e107aa246531",
18
      "blkHash": "230ba8095d5a505e355652f9dcc2b13605419a8fa3d3fd5ddc6d24fd6a902641",
19
      "timestamp": "2019-04-22T02:06:30Z",
20
      "blkHeight": "1",
21
      "sender": "io1vtm2zgn830pn6auc2cvnchgwdaefa9gr4z0s86",
22
      "gasFee": "0"
23
    },
24
    {
25
      "action": {
26
        "core": {
27
          "version": 1,
28
          "gasLimit": "5000000",
29
          "gasPrice": "0",
30
          "transfer": {
31
            "amount": "0",
32
            "recipient": "io1vtm2zgn830pn6auc2cvnchgwdaefa9gr4z0s86",
33
            "payload": "cmNxZ2pzeGZkeHpzenp0cHlkemx6Y2xwbHo6Ly9VMkZzZEdWa1gxOUU0dzJRZ2dQSi82TjM4ZUNVNFlUdk9OeUs4QTVqWjFYSW9RREMybFpCSEdlOWRERmtONlRvSnFhQXhjUHg2SkV6T3YveWlWQWw2YStQeW0rSTAyQnZsZVcybWNLdU1WNnRXSFJIVG5KdXU5ODF4MlhQMm9XOQ=="
34
          }
35
        },
36
        "senderPubKey": "BGR5G9TOfUUQEoCJ+x262Gp+8wv/0/K73OZKl/P6tJEO+CVthBN9yiFyLZFejCeWoyy5WKy14B+iUAdGjPglhQg=",
37
        "signature": "aHHaBSzCb2pkAa6V/oqHruAkvjXHg6LH51LRJob8Cf1hAh6SxjVZlbCtVhVq0BCIJW9vf2Gd/gPLxa56kpZmhQE="
38
      },
39
      "actHash": "b7024bc52f315fafb9cc7677e730aec79767b28fbaa6bdd1f37c1861dd699aba",
40
      "blkHash": "230ba8095d5a505e355652f9dcc2b13605419a8fa3d3fd5ddc6d24fd6a902641",
41
      "timestamp": "2019-04-22T02:06:30Z",
42
      "blkHeight": "1",
43
      "sender": "io1vtm2zgn830pn6auc2cvnchgwdaefa9gr4z0s86",
44
      "gasFee": "0"
45
    }
46
  ],
47
  "total": "5407021"
48
}

Copied!
GetBlockMetasByHash
1
Usage:
2
  Get Block Metadata By Block Hash
3
Request:
4
  ByHash: GetBlockMetaByHashRequest
5
    -BlkHash: Block Hash
6
Response:
7
  BlkMetas: Block Metadata

Copied!
Example:
1
➜  ~ grpcurl -d '{"byHash": {"blkHash": "230ba8095d5a505e355652f9dcc2b13605419a8fa3d3fd5ddc6d24fd6a902641"}}' api.mainnet.iotex.one:443 iotexapi.APIService.GetBlockMetas
2
​
3
{
4
  "blkMetas": [
5
    {
6
      "hash": "230ba8095d5a505e355652f9dcc2b13605419a8fa3d3fd5ddc6d24fd6a902641",
7
      "height": "1",
8
      "timestamp": "2019-04-22T02:06:30Z",
9
      "numActions": "2",
10
      "producerAddress": "io1vtm2zgn830pn6auc2cvnchgwdaefa9gr4z0s86",
11
      "transferAmount": "0",
12
      "txRoot": "1d2a8f412b80a23af5dfd795139a9567e21bbd674c42c48baa0722c8fed828a0",
13
      "receiptRoot": "b325892694c3ab543e6c44da18a25542d140c892391f061fadac47cf1f42d803",
14
      "deltaStateDigest": "7a59812644c0c5188e52ed028ed335c5226f27ea7343647cd1cd19fd2a3e334f"
15
    }
16
  ],
17
  "total": "1"
18
}

Copied!
GetBlockMetasByIndex
1
Usage:
2
  Get Block Metadata By Index
3
Request:
4
  ByIndex: GetBlockMetasByIndexRequest
5
    -Start: Start Block Height
6
    -Count: Number of Blocks
7
Response:
8
  BlkMetas: List of Block Metadata

Copied!
Example:
1
➜  ~ grpcurl -d '{"byIndex": {"start": 1, "count": 2}}' api.mainnet.iotex.one:443 iotexapi.APIService.GetBlockMetas
2
​
3
{
4
  "blkMetas": [
5
    {
6
      "hash": "b7754977cae0f2a45a4ae2b7f0dfc20487e5acfa93594e5eaa1e93f5ec88800f",
7
      "height": 1,
8
      "timestamp": "2019-04-17T00:08:50.466089Z",
9
      "numActions": 1,
10
      "producerAddress": "io1sxm6zl56um2c3ntq5fwqjar4za5ka560x53muy",
11
      "transferAmount": "0",
12
      "txRoot": "285ff4de28a16dafc49d8c46d24fa99433ac08f24be8962c7a01ade65068a34a",
13
      "receiptRoot": "60d78681f8e531307e9ef1916f8ff8d387d922e47d0459e14d575f40ac042195",
14
      "deltaStateDigest": "206c92297a78c59ff6fe3a6351e755fda8ae9bb40b25084e0588b0af43445ca7"
15
    },
16
    {
17
      "hash": "47406baaee6af2775ef61c46373b6d0202b228f11e1a7a2f986f7d617f64f593",
18
      "height": 2,
19
      "timestamp": "2019-04-17T00:09:00.465902Z",
20
      "numActions": 1,
21
      "producerAddress": "io1sxm6zl56um2c3ntq5fwqjar4za5ka560x53muy",
22
      "transferAmount": "0",
23
      "txRoot": "d63be4dc98821a28410f694a4fd71179e79db638496a9510c67e5b1a0fc0dac4",
24
      "receiptRoot": "89cd1950dc9b51f8cf7078ffb38046d31e421c3add9c06abdd3cbcc99e5bf265",
25
      "deltaStateDigest": "8a7d0cee0eb6b6010088e0b4a2996668a29eb595ea83533b9e33fdecc15bf758"
26
    }
27
  ]
28
}
Copied!
GetChainMeta
1
Usage:
2
  Get Blockchain Metadata
3
Request:
4
  N/A
5
Response:
6
  ChainMeta: Blockchain Metadata
Copied!
Example:
1
➜  ~ grpcurl api.iotex.one:443 iotexapi.APIService.GetChainMeta
2
​
3
{
4
  "chainMeta": {
5
    "height": 88,
6
    "numActions": 90,
7
    "epoch": {
8
      "num": 2,
9
      "height": 49,
10
      "gravityChainStartHeight": 49
11
    }
12
  }
13
}
Copied!
GetEpochMeta
1
Usage:
2
  Get Epoch Metadata Given an Epoch Number
3
Request:
4
  EpochNumber: Epoch Number
5
Response:
6
  EpochData: Basic Epoch Information
7
  TotalBlocks: Number of Blocks in the Epoch
8
  BlockProducersInfo: List of Block Producer Information
Copied!
Example:
1
➜  ~ grpcurl -d '{"epochNumber": 1}' api.iotex.one:443 iotexapi.APIService.GetEpochMeta
2
​
3
{
4
  "epochData": {
5
    "num": 1,
6
    "height": 1,
7
    "gravityChainStartHeight": 7502300
8
  },
9
  "totalBlocks": 360,
10
  "blockProducersInfo": [
11
    {
12
      "address": "io1gh7xfrsnj6p5uqgjpk9xq6jg9na28aewgp7a9v",
13
      "votes": "10000000000000000000000000",
14
      "active": true,
15
      "production": 15
16
    },
17
    {
18
      "address": "io1scs89jur7qklzh5vfrmha3c40u8yajjx6kvzg9",
19
      "votes": "10000000000000000000000000",
20
      "active": true,
21
      "production": 15
22
    },
23
    {
24
      "address": "io159fv8mu9d5djk8u2t0flgw4yqmt6fg98uqjka8",
25
      "votes": "10000000000000000000000000",
26
      "active": true,
27
      "production": 15
28
    },
29
    {
30
      "address": "io1cup9k8hl8fp40vrj29ex8djc346780dk223end",
31
      "votes": "10000000000000000000000000",
32
      "active": true,
33
      "production": 15
34
    },
35
    {
36
      "address": "io1wv5m0xyermvr2n0wjx2cjsqwyk863drdl5qfyn",
37
      "votes": "10000000000000000000000000",
38
      "active": true,
39
      "production": 15
40
    },
41
    {
42
      "address": "io1gf08snppu2a2wfd50pjas2j6q2kcxjzqph3pep",
43
      "votes": "10000000000000000000000000",
44
      "active": true,
45
      "production": 15
46
    },
47
    {
48
      "address": "io1u5ff879gg2dw9vfpxr2tsmuaz07e2rea6gvl7s",
49
      "votes": "10000000000000000000000000",
50
      "active": true,
51
      "production": 15
52
    },
53
    {
54
      "address": "io1ar5l5s268rtgzshltnqv88mua06ucm58dx678y",
55
      "votes": "10000000000000000000000000",
56
      "active": true,
57
      "production": 15
58
    },
59
    {
60
      "address": "io1xsx5n94kg2zv64r7tm8vyz9mh86amfak9ka9xx",
61
      "votes": "10000000000000000000000000",
62
      "active": true,
63
      "production": 15
64
    },
65
    {
66
      "address": "io1x9kjkr0qv2fa7j4t2as8lrj223xxsqt4tl7xp7",
67
      "votes": "10000000000000000000000000",
68
      "active": true,
69
      "production": 15
70
    },
71
    {
72
      "address": "io1fks575kklxafq4fwjccmz5d3pmq5ynxk5h6h0v",
73
      "votes": "10000000000000000000000000",
74
      "active": true,
75
      "production": 15
76
    },
77
    {
78
      "address": "io1vtm2zgn830pn6auc2cvnchgwdaefa9gr4z0s86",
79
      "votes": "10000000000000000000000000",
80
      "active": true,
81
      "production": 15
82
    },
83
    {
84
      "address": "io12yxdwewry70gr9fs6fphyfaky9c7gurmzk8f4f",
85
      "votes": "10000000000000000000000000",
86
      "active": true,
87
      "production": 15
88
    },
89
    {
90
      "address": "io1c3r4th3zrk4uhv83a9gr4gvn3y6pzaj6mc84ea",
91
      "votes": "10000000000000000000000000",
92
      "active": true,
93
      "production": 15
94
    },
95
    {
96
      "address": "io15fqav3tugm96ge7anckx0k4gukz5m4mqf0jpv3",
97
      "votes": "10000000000000000000000000",
98
      "active": true,
99
      "production": 15
100
    },
101
    {
102
      "address": "io14vmhs9c75r2ptxdaqrtk0dz7skct30pxmt69d9",
103
      "votes": "10000000000000000000000000",
104
      "active": true,
105
      "production": 15
106
    },
107
    {
108
      "address": "io1v0q5g2f8z6l3v25krl677chdx7g5pwt9kvqfpc",
109
      "votes": "10000000000000000000000000",
110
      "active": true,
111
      "production": 15
112
    },
113
    {
114
      "address": "io1z7mjef7w528nasnsafan0rp6yuvkvq405l6r8j",
115
      "votes": "10000000000000000000000000",
116
      "active": true,
117
      "production": 15
118
    },
119
    {
120
      "address": "io1xsdegzr2hdj5sv5ad4nr0yfgpsd98e40u6svem",
121
      "votes": "10000000000000000000000000",
122
      "active": true,
123
      "production": 15
124
    },
125
    {
126
      "address": "io1nyjs526mnqcsx4twa7nptkg08eclsw5c2dywp4",
127
      "votes": "10000000000000000000000000",
128
      "active": true,
129
      "production": 15
130
    },
131
    {
132
      "address": "io1du4eq4f88n4wyc026l3gamjwetlgsg4jz7j884",
133
      "votes": "10000000000000000000000000",
134
      "active": true,
135
      "production": 15
136
    },
137
    {
138
      "address": "io127ftn4ry6wgxdrw4hcd6gdwqlq70ujk98dvtw5",
139
      "votes": "10000000000000000000000000",
140
      "active": true,
141
      "production": 15
142
    },
143
    {
144
      "address": "io1jafqlvntcxgyp6e0uxctt3tljzc3vyv5hg4ukh",
145
      "votes": "10000000000000000000000000",
146
      "active": true,
147
      "production": 16
148
    },
149
    {
150
      "address": "io15npzu93ug8r3zdeysppnyrcdu2xssz0lcam9l9",
151
      "votes": "10000000000000000000000000",
152
      "active": true,
153
      "production": 14
154
    }
155
  ]
156
}

Copied!
GetLogsByBlock
1
Usage:
2
  Get Logs filtered by contract address and Topics with given Block hash
3
Request:
4
  Filter: LogsFilter
5
    -Address: List of Addresses
6
    -Topics: List of Topics
7
  ByBlock: GetLogsByBlock
8
    -BlockHash: blockhash
9
​
10
Response:
11
  Logs: List of Logs
Copied!
Example:
1
➜  ~ grpcurl -v -plaintext -d '{"filter": {}, "byBlock": {"blockHash": "221e7f14dddd57a739975b943bfffb1cbfcffa1ee043cf693b92af987e42ed93"}}' api.mainnet.iotex.one:443 iotexapi.APIService.GetLogs
Copied!
GetLogsByRange
1
Usage:
2
  Get Logs filtered by contract address and Topics with given Range
3
Request:
4
  Filter: LogsFilter
5
    -Address: List of Addresses
6
    -Topics: List of Topics
7
  ByRange: GetLogsByRange
8
    -FromBlock: Start Block Height
9
    -Count: Count of Blocks
10
​
11
Response:
12
  Logs: List of Logs

Copied!
Example:
1
➜  ~ grpcurl -d '{"filter": {}, "byRange": {"fromBlock": "12000", "count": "2"}}' api.mainnet.iotex.one:443 iotexapi.APIService.GetLogs
2
​
3
{
4
  "logs": [
5
    {
6
      "contractAddress": "io154mvzs09vkgn0hw6gg3ayzw5w39jzp47f8py9v",
7
      "data": "EilpbzFjNXp3aDI0cGM0ejg3dHF3NG02ejZjNHk1NDRwd3N2OG5ycm02NhoUMTYwMDAwMDAwMDAwMDAwMDAwMDA=",
8
      "blkHeight": "12000",
9
      "actHash": "NDSsKbgjqU5jP4LWr2xoq/kpu9s8g0C4tpF/PiDTFkI="
10
    },
11
    {
12
      "contractAddress": "io154mvzs09vkgn0hw6gg3ayzw5w39jzp47f8py9v",
13
      "data": "EilpbzFjNXp3aDI0cGM0ejg3dHF3NG02ejZjNHk1NDRwd3N2OG5ycm02NhoUMTYwMDAwMDAwMDAwMDAwMDAwMDA=",
14
      "blkHeight": "12001",
15
      "actHash": "6+RK0qv5kZ3nJ014NqLlEadmnMaMS1KPWkE5mZLmSGA="
16
    }
17
  ]
18
}
19
​
Copied!
GetRawBlocks
1
Usage:
2
  Get A List of Raw Block Data
3
Request:
4
  StartHeight: Start Block Height
5
  Count: Block Count
6
  WithReceipts: Whether to Include Action Receipts in Each Returned Block
7
Response:
8
  Blocks: A List of Raw Block Data
Copied!
Example:
1
➜  ~ grpcurl -d '{"startHeight": 1, "count": 2, "withReceipts": true}' api.mainnet.iotex.one:443 iotexapi.APIService.GetRawBlocks
2
​
3
{
4
  "blocks": [
5
    {
6
      "block": {
7
        "header": {
8
          "core": {
9
            "version": 1,
10
            "height": 1,
11
            "timestamp": "2019-06-17T23:33:04.755448Z",
12
            "prevBlockHash": "N9XWktUXQo60gwwqV17n5trTKkbUp/Ob6UY841g+AtA=",
13
            "txRoot": "5Pn9BOMAgzj0LX9o6AD8O/FbDueiA5eS+9MUMzQ6QwY=",
14
            "deltaStateDigest": "tE9Ywa/2MvNDO7F8scFh9/4ijrGXTClVunKbp5eeU8M=",
15
            "receiptRoot": "EbGK2TCBJbVMEn04tBRy0PdceJ1O2N3IxnU7Fggjl2o="
16
          },
17
          "producerPubkey": "BB5cvAz6DM+BTzw9RADTmMqz0WPDofHDEGQ2kNl20p49+i0O2b5yH6Xc7EeqethWkyI8nw1BrrRleRkqfsHU9m8=",
18
          "signature": "oZxrQvUteVeq+SMCxg6I+MwJ4IkKWFzDhFi3hIQ9j9IYL69RRWsRc+pxXAjdfRCiLuCXGnkaP+nUXnR3Atm8EwA="
19
        },
20
        "body": {
21
          "actions": [
22
            {
23
              "core": {
24
                "version": 1,
25
                "gasPrice": "0",
26
                "grantReward": {
27
                  "height": 1
28
                }
29
              },
30
              "senderPubKey": "BB5cvAz6DM+BTzw9RADTmMqz0WPDofHDEGQ2kNl20p49+i0O2b5yH6Xc7EeqethWkyI8nw1BrrRleRkqfsHU9m8=",
31
              "signature": "gE9H+i0EZNTVHhoX7fq4xn6H8FqBrFKK0YyfcH16mrFT0rSvgVDb/ov2hAwgMh5kJVHaD8TG6UX7fayK5lpCXQA="
32
            }
33
          ]
34
        },
35
        "footer": {
36
          "timestamp": "0001-01-01T00:00:00Z"
37
        }
38
      },
39
      "receipts": [
40
        {
41
          "blkHeight": 1,
42
          "actHash": "5Pn9BOMAgzj0LX9o6AD8O/FbDueiA5eS+9MUMzQ6QwY=",
43
          "contractAddress": "io154mvzs09vkgn0hw6gg3ayzw5w39jzp47f8py9v"
44
        }
45
      ]
46
    },
47
    {
48
      "block": {
49
        "header": {
50
          "core": {
51
            "version": 1,
52
            "height": 2,
53
            "timestamp": "2019-06-17T23:33:14.756354Z",
54
            "prevBlockHash": "7bI37oyjBvl+TTx5Fw089xCe8AJb7YneCsmqOLiJ88k=",
55
            "txRoot": "qQZkW9iZ+xsl0SjVJmsIDDpQ9RcWyge/sBcvHOZFgKQ=",
56
            "deltaStateDigest": "S7dJ9+p/BUNaiRFQLl6+Lc/u5B5s4jlJ5LldIFwof9c=",
57
            "receiptRoot": "S2ZBa1FtEUSDmBqTbnS4w4RfhHfyyDJofaxL1U36+9I="
58
          },
59
          "producerPubkey": "BB5cvAz6DM+BTzw9RADTmMqz0WPDofHDEGQ2kNl20p49+i0O2b5yH6Xc7EeqethWkyI8nw1BrrRleRkqfsHU9m8=",
60
          "signature": "s/JZHbuZaMKOqWACHsGbezciRBSS7XYU9QuY2w3BgM8pEYWtYXZYWVJiHU3r0Z1Z7PXFMKc1glpONXkLiXwReQA="
61
        },
62
        "body": {
63
          "actions": [
64
            {
65
              "core": {
66
                "version": 1,
67
                "gasPrice": "0",
68
                "grantReward": {
69
                  "height": 2
70
                }
71
              },
72
              "senderPubKey": "BB5cvAz6DM+BTzw9RADTmMqz0WPDofHDEGQ2kNl20p49+i0O2b5yH6Xc7EeqethWkyI8nw1BrrRleRkqfsHU9m8=",
73
              "signature": "gMlB2v2RwSHnNuilZX89K+EOtCKDfmfouI97GO+DcU82VHm9LE4NG1TVgUQe6z94aOSHrEwyUKtINuv5QOmNIgA="
74
            }
75
          ]
76
        },
77
        "footer": {
78
          "timestamp": "0001-01-01T00:00:00Z"
79
        }
80
      },
81
      "receipts": [
82
        {
83
          "blkHeight": 2,
84
          "actHash": "qQZkW9iZ+xsl0SjVJmsIDDpQ9RcWyge/sBcvHOZFgKQ=",
85
          "contractAddress": "io154mvzs09vkgn0hw6gg3ayzw5w39jzp47f8py9v"
86
        }
87
      ]
88
    }
89
  ]
90
}
Copied!
GetReceiptByAction
1
Usage:
2
  Get Action Receipt By Action Hash
3
Request:
4
  ActionHash: Action Hash
5
Response:
6
  Receipt: Action Receipt

Copied!
Example:
1
➜  ~ grpcurl -d '{"actionHash": "dd2e83336f1ff219b1e54558f0627e1f556ed2caeedb44b758b0e107aa246531"}' api.mainnet.iotex.one:443 iotexapi.APIService.GetReceiptByAction
2
{
3
  "receiptInfo": {
4
    "receipt": {
5
      "status": "1",
6
      "blkHeight": "1",
7
      "actHash": "3S6DM28f8hmx5UVY8GJ+H1Vu0sru20S3WLDhB6okZTE=",
8
      "contractAddress": "io154mvzs09vkgn0hw6gg3ayzw5w39jzp47f8py9v",
9
      "logs": [
10
        {
11
          "contractAddress": "io154mvzs09vkgn0hw6gg3ayzw5w39jzp47f8py9v",
12
          "data": "EilpbzFjNXp3aDI0cGM0ejg3dHF3NG02ejZjNHk1NDRwd3N2OG5ycm02NhoUMTYwMDAwMDAwMDAwMDAwMDAwMDA=",
13
          "blkHeight": "1",
14
          "actHash": "3S6DM28f8hmx5UVY8GJ+H1Vu0sru20S3WLDhB6okZTE="
15
        }
16
      ]
17
    },
18
    "blkHash": "230ba8095d5a505e355652f9dcc2b13605419a8fa3d3fd5ddc6d24fd6a902641"
19
  }
20
}
Copied!
GetServerMeta
1
Usage:
2
  Get Server Metadata
3
Request:
4
  N/A
5
Reponse:
6
  ServerMeta: Server Metadata
Copied!
Example:
1
➜  ~ grpcurl api.iotex.one:443 iotexapi.APIService.GetServerMeta
2
​
3
{
4
  "serverMeta": {
5
    "packageVersion": "v0.7.0-35-g3baac429",
6
    "packageCommitID": "3baac429420ae74a2d1e97a866f745ca796fc192",
7
    "gitStatus": "clean",
8
    "goVersion": "go version go1.12.5 darwin/amd64",
9
    "buildTime": "2019-06-17-PDT/16:32:37"
10
  }
11
}
Copied!
GetTransactionLogByActionHash
1
Usage:
2
  Get Transaction log By Action hash
3
Request:
4
  ActionHash: Action Hash
5
​
6
Response:
7
  GetTransactionLogByActionHashResponse: Transaction logs in Action
Copied!
Example:
1
grpcurl -d '{"actionHash":"d4b3c8373ad28d46625902ab92033098a53f7283335847330e0b46a1fd112d8d"}' api.iotex.one:443 iotexapi.APIService.GetTransactionLogByActionHash
2
{
3
  "transactionLog": {
4
    "actionHash": "1LPINzrSjUZiWQKrkgMwmKU/coMzWEczDgtGof0RLY0=",
5
    "numTransactions": "40",
6
    "transactions": [
7
      {
8
        "amount": "650975000000000000",
9
        "sender": "io1scqu4w9z9wsakpxwjz0yasw7u424huaswwpy76",
10
        "recipient": "io0000000000000000000000rewardingprotocol",
11
        "type": "GAS_FEE"
12
      },
13
      {
14
        "amount": "6532163000000000000000000",
15
        "sender": "io1scqu4w9z9wsakpxwjz0yasw7u424huaswwpy76",
16
        "recipient": "io1lvemm43lz6np0hzcqlpk0kpxxww623z5hs4mwu"
17
      },
18
      {
19
        "amount": "100000000000000000000",
20
        "sender": "io1lvemm43lz6np0hzcqlpk0kpxxww623z5hs4mwu",
21
        "recipient": "io1tef0w2vn288htckthslg7ut6qgula6ssn3rukx"
22
      },
23
      {
24
        "amount": "1800000000000000000000",
25
        "sender": "io1lvemm43lz6np0hzcqlpk0kpxxww623z5hs4mwu",
26
        "recipient": "io1mzly3mzaw0nesn96zsmp3gqvhj929ejkl6rsh9"
27
      },
28
      ...
29
      {
30
        "amount": "14600000000000000000000",
31
        "sender": "io1lvemm43lz6np0hzcqlpk0kpxxww623z5hs4mwu",
32
        "recipient": "io10p639dt4xf9cf256ctzuem63pgej827zwl2035"
33
      },
34
      {
35
        "amount": "8400000000000000000000",
36
        "sender": "io1lvemm43lz6np0hzcqlpk0kpxxww623z5hs4mwu",
37
        "recipient": "io1ap5smf54awc7vngtgzsmvvppswza0y3t0gng90"
38
      },
39
​
40
      {
41
        "amount": "9000000000000000000000",
42
        "sender": "io1lvemm43lz6np0hzcqlpk0kpxxww623z5hs4mwu",
43
        "recipient": "io1ea0pdyphktxt42yjlt6gtktalls6thasck6g2v"
44
      }
45
    ]
46
  },
47
  "blockIdentifier": {
48
    "hash": "457d95613c3e8007b0dd2605f29dca5321e453209e4750c43d0613f1d93b6854",
49
    "height": "5202793"
50
  }
51
}
Copied!
GetTransactionLogByBlockHeight
1
Usage:
2
  Get Transaction log By Block Height
3
Request:
4
  BlockHeight: Block Height
5
​
6
Response:
7
  GetTransactionLogByBlockHeightResponse: Transaction logs in Block
Copied!
Example:
1
➜  ~  grpcurl -d '{"blockHeight":5202793}' api.iotex.one:443 iotexapi.APIService.GetTransactionLogByBlockHeight
2
{
3
  "transactionLogs": {
4
    "logs": [
5
      {
6
        "actionHash": "1LPINzrSjUZiWQKrkgMwmKU/coMzWEczDgtGof0RLY0=",
7
        "numTransactions": "40",
8
        "transactions": [
9
          {
10
            "amount": "650975000000000000",
11
            "sender": "io1scqu4w9z9wsakpxwjz0yasw7u424huaswwpy76",
12
            "recipient": "io0000000000000000000000rewardingprotocol",
13
            "type": "GAS_FEE"
14
          },
15
          {
16
            "amount": "6532163000000000000000000",
17
            "sender": "io1scqu4w9z9wsakpxwjz0yasw7u424huaswwpy76",
18
            "recipient": "io1lvemm43lz6np0hzcqlpk0kpxxww623z5hs4mwu"
19
          },
20
          {
21
            "amount": "100000000000000000000",
22
            "sender": "io1lvemm43lz6np0hzcqlpk0kpxxww623z5hs4mwu",
23
            "recipient": "io1tef0w2vn288htckthslg7ut6qgula6ssn3rukx"
24
          },
25
          {
26
            "amount": "1800000000000000000000",
27
            "sender": "io1lvemm43lz6np0hzcqlpk0kpxxww623z5hs4mwu",
28
            "recipient": "io1mzly3mzaw0nesn96zsmp3gqvhj929ejkl6rsh9"
29
          },
30
          {
31
            "amount": "425000000000000000000",
32
            "sender": "io1lvemm43lz6np0hzcqlpk0kpxxww623z5hs4mwu",
33
            "recipient": "io1u9khn0q9g40mfca9dhkg35dr8rtdds65uvc7s0"
34
          },
35
          {
36
            "amount": "499000000000000000000000",
37
            "sender": "io1lvemm43lz6np0hzcqlpk0kpxxww623z5hs4mwu",
38
            "recipient": "io1lvukz4482xweap8xm7zsa5fdj85wlnqgympjsm"
39
          },
40
          ...
41
          {
42
            "amount": "9000000000000000000000",
43
            "sender": "io1lvemm43lz6np0hzcqlpk0kpxxww623z5hs4mwu",
44
            "recipient": "io1ea0pdyphktxt42yjlt6gtktalls6thasck6g2v"
45
          }
46
        ]
47
      }
48
    ]
49
  },
50
  "blockIdentifier": {
51
    "hash": "457d95613c3e8007b0dd2605f29dca5321e453209e4750c43d0613f1d93b6854",
52
    "height": "5202793"
53
  }
54
}
Copied!
GetUnconfirmedActionsByAddress
1
Usage:
2
  Get Unconfirmed Actions By Address
3
Request:
4
  UnconfirmedByAddr: GetUnconfirmedActionsByAddressRequest
5
    -Address: Encoded Address
6
    -Start: Start Index of Unconfirmed Actions
7
    -Count: Number of Unconfirmed Actions
8
Resposne:
9
  ActionInfo: List of Action Info
Copied!
Example:
1
➜  ~ grpcurl -d '{"unconfirmedByAddr": {"address": "io1juvx5g063eu4ts832nukp4vgcwk2gnc5cu9ayd", "start": 0, "count": 1}}' api.mainnet.iotex.one:443 iotexapi.APIService.GetActions
2
​
3
{
4
​
5
}
Copied!
ReadContract
1
Usage:
2
  Read Contract State
3
Request:
4
  Action: Action (Must Be An Execution)
5
Response:
6
  Data: Return Value in Execution Receipt
Copied!
Example:
1
➜  ~ grpcurl -plaintext -d '{"action": {"core": {"version": 1, "nonce": 2, "gasLimit": 10000, "gasPrice": "1000000000000", "execution": {"amount": "0", "contract": ""}}, "senderPubKey": "BOk7WxyPumkmNlKkg61VMY5O7VtRIjFMt/2wd9jHKVCXzsku5QsRCNx0lalyDlkh5W0wSON6vmpnFtfJuRPp8uY=", "signature": "9mrqFBggiRocZhkRVUswxs83NaEFNdEYYczI8049vlovHEP4YMQz+3Isznc3CrYaJxAbc2PTIz7y2meerJ8bHAA="}}' 127.0.0.1:14014 iotexapi.APIService.ReadContract
2
​
3
{
4
  "receipt": {
5
    "status": 1,
6
    "blkHeight": 26,
7
    "actHash": "2bAgDlDdF84K+XNCW95wdjMpmQqVP2b04ghyMXoN6J4=",
8
    "gasConsumed": 10000,
9
    "contractAddress": "io18vlvlj0v02yye70kpqtzhu4uek3qqz27zm7g42"
10
  }
11
}
Copied!
ReadState
1
Usage:
2
  Read State on Blockchain
3
Request:
4
  ProtocolID: Protocol ID
5
  MethodName: Method To Be Invoked To Read State
6
  Arguments: List of Method Arguments
7
  Height: BlockHeight of Request // optional, if empty, read from tip
8
Response:
9
  Data: State Result

Copied!
Example:
1
➜  ~ grpcurl -d '{"protocolID": "cmV3YXJkaW5n", "methodName": "VW5jbGFpbWVkQmFsYW5jZQ==", "arguments": "aW8xanV2eDVnMDYzZXU0dHM4MzJudWtwNHZnY3drMmduYzVjdTlheWQ="}' api.iotex.one:443 iotexapi.APIService.ReadState
2
​
3
{
4
  "data": "MA=="
5
}

Copied!
SendAction
1
Usage:
2
  Send Action
3
Request:
4
  Action: Action
5
Response:
6
  ActionHash: Hash of Action
Copied!
Example:
1
➜  ~ grpcurl -plaintext -d '{"action": {"core": 