iotex-core - gRPC API
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.
Endpoint | Provider | More |
---|---|---|
api.iotex.one:443 | IoTeX Foundation | |
api.mainnet.iotex.one:443 | IoTeX Foundation |
Testnet
Endpoint | Text | More |
---|---|---|
api.testnet.iotex.one:443 | IoTeX Foundation |
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.Usage:
Get Estimated Action Gas Consumption By Execution
Request:
Execution: iotextypes.Execution
-Amount: Execution Amount
-Contract: Contract Address
-Data: Data
CallerAddress: Address of Caller
Response:
Gas: Estimated Gas Amount
Example:
➜ ~ grpcurl -d '{"execution": {"amount":"0", "contract":"io154mvzs09vkgn0hw6gg3ayzw5w39jzp47f8py9v"}, "callerAddress": "io1juvx5g063eu4ts832nukp4vgcwk2gnc5cu9ayd"}' api.mainnet.iotex.one:443 iotexapi.APIService.EstimateActionGasConsumption
{
"gas": "10000"
}
Usage:
Get Estimated Action Gas Consumption By Transfer
Request:
Transfer: iotextypes.Transfer
-Amount: Transfer Amount
-Recipient: Recipient Address
-Payload: Payload
CallerAddress: Address of Caller
Response:
Gas: Estimated Gas Amount
Example:
➜ ~ grpcurl -d '{"transfer": {"amount":"100000", "recipient":"io1juvx5g063eu4ts832nukp4vgcwk2gnc5cu9ayd"}, "callerAddress": "io1juvx5g063eu4ts832nukp4vgcwk2gnc5cu9ayd"}' api.mainnet.iotex.one:443 iotexapi.APIService.EstimateActionGasConsumption
{
"gas": "10000"
}
Usage:
Get Estimated Gas For Action
Request:
Action: Action
Response:
Gas: Gas
Example:
➜ ~ 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
{
"gas": 10000
}
Usage:
Get Account Details
Request:
Address: Account Encoded Address
Response:
AccountMeta: Account Metadata
Example:
➜ ~ grpcurl -d '{"address": "io1juvx5g063eu4ts832nukp4vgcwk2gnc5cu9ayd"}' api.mainnet.iotex.one:443 iotexapi.APIService.GetAccount
{
"accountMeta": {
"address": "io1juvx5g063eu4ts832nukp4vgcwk2gnc5cu9ayd",
"balance": "0",
"nonce": "2",
"pendingNonce": "3",
"numActions": "2"
}
}
Usage:
Get Actions By Address
Request:
ByAddr: GetActionsByAddressRequest
-Address: Encoded Address
-Start: Start Index of Actions
-Count: Number of Actions
Resposne:
ActionInfo: List of Action Info
Example:
➜ ~ grpcurl -d '{"byAddr": {"address": "io1juvx5g063eu4ts832nukp4vgcwk2gnc5cu9ayd", "start": 0, "count": 1}}' api.mainnet.iotex.one:443 iotexapi.APIService.GetActions
Resolved method descriptor:
rpc GetActions ( .iotexapi.GetActionsRequest ) returns ( .iotexapi.GetActionsResponse );
Request metadata to send:
(empty)
Response headers received:
content-type: application/grpc
Response contents:
{
"actionInfo": [
{
"action": {
"core": {
"version": 1,
"nonce": 1,
"gasLimit": 10000,
"gasPrice": "10000000000000",
"transfer": {
"amount": "1000000000000000000",
"recipient": "io1sxm6zl56um2c3ntq5fwqjar4za5ka560x53muy"
}
},
"senderPubKey": "BOk7WxyPumkmNlKkg61VMY5O7VtRIjFMt/2wd9jHKVCXzsku5QsRCNx0lalyDlkh5W0wSON6vmpnFtfJuRPp8uY=",
"signature": "9mrqFBggiRocZhkRVUswxs83NaEFNdEYYczI8049vlovHEP4YMQz+3Isznc3CrYaJxAbc2PTIz7y2meerJ8bHAA="
},
"actHash": "060a93a4784469f9e587da0c90ed20df58b0effb50d6b8ddcd9a4c65ad55fcbd",
"blkHash": "6344115bcd43b7315ffdf5338d0f97b26caed7734efea034a27208f64670f5e9",
"timestamp": "2019-04-17T00:10:30.468419Z"
}
]
}
Usage:
Get Actions By Block
Request:
ByBlk: GetActionsByBlockRequest
-BlkHash: Block Hash
-Start: Start Index of Actions
-Count: Number of Actions
Resposne:
ActionInfo: List of ActionInfo
Example:
➜ ~ grpcurl -d '{"byBlk": {"blkHash": "6344115bcd43b7315ffdf5338d0f97b26caed7734efea034a27208f64670f5e9", "start": 0, "count": 1}}' api.mainnet.iotex.one:443 iotexapi.APIService.GetActions
{
"actionInfo": [
{
"action": {
"core": {
"version": 1,
"gasPrice": "0",
"grantReward": {
"height": "1"
}
},
"senderPubKey": "BGR5G9TOfUUQEoCJ+x262Gp+8wv/0/K73OZKl/P6tJEO+CVthBN9yiFyLZFejCeWoyy5WKy14B+iUAdGjPglhQg=",
"signature": "fsCLFdClaIYAbwcyeUduhYOzvdncK412GqfEYQqxEwlZXMVfbrrOXVsRAmrtnz69J/t/Z+vlpeTfmqN4LkGt0gA="
},
"actHash": "dd2e83336f1ff219b1e54558f0627e1f556ed2caeedb44b758b0e107aa246531",
"blkHash": "230ba8095d5a505e355652f9dcc2b13605419a8fa3d3fd5ddc6d24fd6a902641",
"timestamp": "2019-04-22T02:06:30Z",
"blkHeight": "1",
"sender": "io1vtm2zgn830pn6auc2cvnchgwdaefa9gr4z0s86"
}
],
"total": "2"
}
Usage:
Get Action By Action Hash
Request:
ByHash: GetActionByHashRequest
-ActionHash: Hash of Action
-CheckPending: Wether To Check Pending Actions in Action Pool
Response:
ActionInfo: Action Info
Example:
➜ ~ grpcurl -d '{"byHash": {"actionHash": "b7024bc52f315fafb9cc7677e730aec79767b28fbaa6bdd1f37c1861dd699aba", "checkPending": false}}' api.mainnet.iotex.one:443 iotexapi.APIService.GetActions
{
"actionInfo": [
{
"action": {
"core": {
"version": 1,
"gasLimit": "5000000",
"gasPrice": "0",
"transfer": {
"amount": "0",
"recipient": "io1vtm2zgn830pn6auc2cvnchgwdaefa9gr4z0s86",
"payload": "cmNxZ2pzeGZkeHpzenp0cHlkemx6Y2xwbHo6Ly9VMkZzZEdWa1gxOUU0dzJRZ2dQSi82TjM4ZUNVNFlUdk9OeUs4QTVqWjFYSW9RREMybFpCSEdlOWRERmtONlRvSnFhQXhjUHg2SkV6T3YveWlWQWw2YStQeW0rSTAyQnZsZVcybWNLdU1WNnRXSFJIVG5KdXU5ODF4MlhQMm9XOQ=="
}
},
"senderPubKey": "BGR5G9TOfUUQEoCJ+x262Gp+8wv/0/K73OZKl/P6tJEO+CVthBN9yiFyLZFejCeWoyy5WKy14B+iUAdGjPglhQg=",
"signature": "aHHaBSzCb2pkAa6V/oqHruAkvjXHg6LH51LRJob8Cf1hAh6SxjVZlbCtVhVq0BCIJW9vf2Gd/gPLxa56kpZmhQE="
},
"actHash": "b7024bc52f315fafb9cc7677e730aec79767b28fbaa6bdd1f37c1861dd699aba",
"blkHash": "230ba8095d5a505e355652f9dcc2b13605419a8fa3d3fd5ddc6d24fd6a902641",
"timestamp": "2019-04-22T02:06:30Z",
"blkHeight": "1",
"sender": "io1vtm2zgn830pn6auc2cvnchgwdaefa9gr4z0s86",
"gasFee": "0"
}
],
"total": "1"
}
Usage:
Get Actions By Index
Request:
ByIndex: GetActionsByIndexRequest
-Start: Start Index of Actions
-Count: Number of Actions
Response:
ActionInfo: List of Action Info
Example:
➜ ~ grpcurl -d '{"byIndex": {"start": 0, "count": 2}}' api.mainnet.iotex.one:443 iotexapi.APIService.GetActions
{
"actionInfo": [
{
"action": {
"core": {
"version": 1,
"gasPrice": "0",
"grantReward": {
"height": "1"
}
},
"senderPubKey": "BGR5G9TOfUUQEoCJ+x262Gp+8wv/0/K73OZKl/P6tJEO+CVthBN9yiFyLZFejCeWoyy5WKy14B+iUAdGjPglhQg=",
"signature": "fsCLFdClaIYAbwcyeUduhYOzvdncK412GqfEYQqxEwlZXMVfbrrOXVsRAmrtnz69J/t/Z+vlpeTfmqN4LkGt0gA="
},
"actHash": "dd2e83336f1ff219b1e54558f0627e1f556ed2caeedb44b758b0e107aa246531",
"blkHash": "230ba8095d5a505e355652f9dcc2b13605419a8fa3d3fd5ddc6d24fd6a902641",
"timestamp": "2019-04-22T02:06:30Z",
"blkHeight": "1",
"sender": "io1vtm2zgn830pn6auc2cvnchgwdaefa9gr4z0s86",
"gasFee": "0"
},
{
"action": {
"core": {
"version": 1,
"gasLimit": "5000000",
"gasPrice": "0",
"transfer": {
"amount": "0",
"recipient": "io1vtm2zgn830pn6auc2cvnchgwdaefa9gr4z0s86",
"payload": "cmNxZ2pzeGZkeHpzenp0cHlkemx6Y2xwbHo6Ly9VMkZzZEdWa1gxOUU0dzJRZ2dQSi82TjM4ZUNVNFlUdk9OeUs4QTVqWjFYSW9RREMybFpCSEdlOWRERmtONlRvSnFhQXhjUHg2SkV6T3YveWlWQWw2YStQeW0rSTAyQnZsZVcybWNLdU1WNnRXSFJIVG5KdXU5ODF4MlhQMm9XOQ=="
}
},
"senderPubKey": "BGR5G9TOfUUQEoCJ+x262Gp+8wv/0/K73OZKl/P6tJEO+CVthBN9yiFyLZFejCeWoyy5WKy14B+iUAdGjPglhQg=",
"signature": "aHHaBSzCb2pkAa6V/oqHruAkvjXHg6LH51LRJob8Cf1hAh6SxjVZlbCtVhVq0BCIJW9vf2Gd/gPLxa56kpZmhQE="
},
"actHash": "b7024bc52f315fafb9cc7677e730aec79767b28fbaa6bdd1f37c1861dd699aba",
"blkHash": "230ba8095d5a505e355652f9dcc2b13605419a8fa3d3fd5ddc6d24fd6a902641",
"timestamp": "2019-04-22T02:06:30Z",
"blkHeight": "1",
"sender": "io1vtm2zgn830pn6auc2cvnchgwdaefa9gr4z0s86",
"gasFee": "0"
}
],
"total": "5407021"
}
Usage:
Get Block Metadata By Block Hash
Request:
ByHash: GetBlockMetaByHashRequest
-BlkHash: Block Hash
Response:
BlkMetas: Block Metadata
Example:
➜ ~ grpcurl -d '{"byHash": {"blkHash": "230ba8095d5a505e355652f9dcc2b13605419a8fa3d3fd5ddc6d24fd6a902641"}}' api.mainnet.iotex.one:443 iotexapi.APIService.GetBlockMetas
{
"blkMetas": [
{
"hash": "230ba8095d5a505e355652f9dcc2b13605419a8fa3d3fd5ddc6d24fd6a902641",
"height": "1",
"timestamp": "2019-04-22T02:06:30Z",
"numActions": "2",
"producerAddress": "io1vtm2zgn830pn6auc2cvnchgwdaefa9gr4z0s86",
"transferAmount": "0",
"txRoot": "1d2a8f412b80a23af5dfd795139a9567e21bbd674c42c48baa0722c8fed828a0",
"receiptRoot": "b325892694c3ab543e6c44da18a25542d140c892391f061fadac47cf1f42d803",
"deltaStateDigest": "7a59812644c0c5188e52ed028ed335c5226f27ea7343647cd1cd19fd2a3e334f"
}
],
"total": "1"
}
Usage:
Get Block Metadata By Index
Request:
ByIndex: GetBlockMetasByIndexRequest
-Start: Start Block Height
-Count: Number of Blocks
Response:
BlkMetas: List of Block Metadata
Example:
➜ ~ grpcurl -d '{"byIndex": {"start": 1, "count": 2}}' api.mainnet.iotex.one:443 iotexapi.APIService.GetBlockMetas