IOTA

IOTA Coin Query API

Coin and balance-oriented JSON-RPC methods for the IOTA blockchain. Provides iotax_getAllBalances to retrieve total balances across all coin types for an address, iotax_getAllCoins to list all coin objects owned by an address, iotax_getBalance for the balance of a specific coin type, iotax_getCirculatingSupply to retrieve circulating supply summary, iotax_getCoinMetadata for token symbol, decimals and description, iotax_getCoins to list coins of a specific type with pagination, and iotax_getTotalSupply to return the total supply for a given coin type.

GitHub OpenAPI

Documentation

📖
Documentation
https://docs.iota.org/iota-api-ref
📖
APIReference
https://docs.iota.org/iota-api-ref

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/iota/refs/heads/main/openapi/iota-jsonrpc-openapi.json

OpenAPI Specification

iota-jsonrpc-openapi.json Raw ↑ 
{
  "openapi": "3.0.3",
  "info": {
    "title": "IOTA JSON-RPC API",
    "description": "IOTA JSON-RPC API for interaction with IOTA full node or indexer. All requests are HTTP POST to the node endpoint. Covers iota_ (Read, Write, Move Utils), iotax_ (Extended, Coin Query, Governance), and unsafe_ (Transaction Builder) method namespaces.",
    "version": "1.26.0-alpha",
    "contact": {
      "name": "IOTA Foundation",
      "email": "[email protected]",
      "url": "https://docs.iota.org/"
    },
    "license": {
      "name": "Apache-2.0",
      "url": "https://opensource.org/licenses/Apache-2.0"
    },
    "x-openrpc-source": "https://raw.githubusercontent.com/iotaledger/iota/develop/crates/iota-open-rpc/spec/openrpc.json"
  },
  "externalDocs": {
    "description": "IOTA API Reference",
    "url": "https://docs.iota.org/iota-api-ref"
  },
  "servers": [
    {
      "url": "https://api.mainnet.iota.cafe",
      "description": "IOTA Mainnet full node"
    },
    {
      "url": "https://api.testnet.iota.cafe",
      "description": "IOTA Testnet full node"
    },
    {
      "url": "https://api.devnet.iota.cafe",
      "description": "IOTA Devnet full node"
    },
    {
      "url": "https://indexer.mainnet.iota.cafe",
      "description": "IOTA Mainnet indexer (iotax_ methods)"
    },
    {
      "url": "https://indexer.testnet.iota.cafe",
      "description": "IOTA Testnet indexer (iotax_ methods)"
    }
  ],
  "tags": [
    {
      "name": "Read",
      "description": "Core read operations: objects, checkpoints, transactions, events, protocol config"
    },
    {
      "name": "Write",
      "description": "Transaction execution, dry run, and dev inspection"
    },
    {
      "name": "Move Utils",
      "description": "Move smart contract introspection: modules, functions, structs"
    },
    {
      "name": "Extended",
      "description": "Indexer-exclusive methods for advanced queries, events, dynamic fields, IOTA Names"
    },
    {
      "name": "Coin Query",
      "description": "Coin and balance queries: balances, coins list, metadata, supply"
    },
    {
      "name": "Governance",
      "description": "Governance, staking, validator, epoch, and system state queries"
    },
    {
      "name": "Transaction Builder",
      "description": "Build unsigned transactions for transfers, staking, Move calls (unsafe_ prefix)"
    }
  ],
  "paths": {
    "/iota_devInspectTransactionBlock": {
      "post": {
        "operationId": "iota_devInspectTransactionBlock",
        "summary": "iota_devInspectTransactionBlock",
        "description": "Runs the transaction in dev-inspect mode. Which allows for nearly any transaction (or Move call) with any arguments. Detailed results are provided, including both the transaction effects and any return values.",
        "tags": [
          "Write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "jsonrpc",
                  "id",
                  "method"
                ],
                "properties": {
                  "jsonrpc": {
                    "type": "string",
                    "enum": [
                      "2.0"
                    ],
                    "description": "JSON-RPC protocol version"
                  },
                  "id": {
                    "oneOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "string"
                      }
                    ],
                    "description": "Request identifier"
                  },
                  "method": {
                    "type": "string",
                    "enum": [
                      "iota_devInspectTransactionBlock"
                    ],
                    "description": "The JSON-RPC method name"
                  },
                  "params": {
                    "type": "array",
                    "description": "Method parameters",
                    "items": {}
                  }
                }
              },
              "example": {
                "jsonrpc": "2.0",
                "id": 1,
                "method": "iota_devInspectTransactionBlock",
                "params": []
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful JSON-RPC response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "jsonrpc": {
                      "type": "string",
                      "example": "2.0"
                    },
                    "id": {
                      "oneOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "string"
                        }
                      ]
                    },
                    "result": {
                      "$ref": "#/components/schemas/DevInspectResults"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "JSON-RPC error response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "jsonrpc": {
                      "type": "string"
                    },
                    "id": {
                      "oneOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "string"
                        }
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "integer"
                        },
                        "message": {
                          "type": "string"
                        },
                        "data": {}
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/iota_dryRunTransactionBlock": {
      "post": {
        "operationId": "iota_dryRunTransactionBlock",
        "summary": "iota_dryRunTransactionBlock",
        "description": "Return transaction execution effects including the gas cost summary, while the effects are not committed to the chain.",
        "tags": [
          "Write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "jsonrpc",
                  "id",
                  "method"
                ],
                "properties": {
                  "jsonrpc": {
                    "type": "string",
                    "enum": [
                      "2.0"
                    ],
                    "description": "JSON-RPC protocol version"
                  },
                  "id": {
                    "oneOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "string"
                      }
                    ],
                    "description": "Request identifier"
                  },
                  "method": {
                    "type": "string",
                    "enum": [
                      "iota_dryRunTransactionBlock"
                    ],
                    "description": "The JSON-RPC method name"
                  },
                  "params": {
                    "type": "array",
                    "description": "Method parameters",
                    "items": {}
                  }
                }
              },
              "example": {
                "jsonrpc": "2.0",
                "id": 1,
                "method": "iota_dryRunTransactionBlock",
                "params": []
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful JSON-RPC response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "jsonrpc": {
                      "type": "string",
                      "example": "2.0"
                    },
                    "id": {
                      "oneOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "string"
                        }
                      ]
                    },
                    "result": {
                      "$ref": "#/components/schemas/DryRunTransactionBlockResponse"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "JSON-RPC error response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "jsonrpc": {
                      "type": "string"
                    },
                    "id": {
                      "oneOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "string"
                        }
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "integer"
                        },
                        "message": {
                          "type": "string"
                        },
                        "data": {}
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/iota_executeTransactionBlock": {
      "post": {
        "operationId": "iota_executeTransactionBlock",
        "summary": "iota_executeTransactionBlock",
        "description": "Execute the transaction and wait for results if desired. Request types: 1. WaitForEffectsCert: waits for TransactionEffectsCert and then return to    client. This mode is a proxy for transaction finality. 2. WaitForLocalExecution: waits for TransactionEffectsCert and make sure the    node executed the transaction locally before returning the client. The    local execution makes sure this node is aware of this transaction when    client fires subsequent queries. However if the node fails to execute the    transaction locally in a timely manner, a bool type in the response is    set to false to indicated the case. request_type is default to be `WaitForEffectsCert` unless options.show_events or options.show_effects is true",
        "tags": [
          "Write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "jsonrpc",
                  "id",
                  "method"
                ],
                "properties": {
                  "jsonrpc": {
                    "type": "string",
                    "enum": [
                      "2.0"
                    ],
                    "description": "JSON-RPC protocol version"
                  },
                  "id": {
                    "oneOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "string"
                      }
                    ],
                    "description": "Request identifier"
                  },
                  "method": {
                    "type": "string",
                    "enum": [
                      "iota_executeTransactionBlock"
                    ],
                    "description": "The JSON-RPC method name"
                  },
                  "params": {
                    "type": "array",
                    "description": "Method parameters",
                    "items": {}
                  }
                }
              },
              "example": {
                "jsonrpc": "2.0",
                "id": 1,
                "method": "iota_executeTransactionBlock",
                "params": []
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful JSON-RPC response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "jsonrpc": {
                      "type": "string",
                      "example": "2.0"
                    },
                    "id": {
                      "oneOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "string"
                        }
                      ]
                    },
                    "result": {
                      "$ref": "#/components/schemas/TransactionBlockResponse"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "JSON-RPC error response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "jsonrpc": {
                      "type": "string"
                    },
                    "id": {
                      "oneOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "string"
                        }
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "integer"
                        },
                        "message": {
                          "type": "string"
                        },
                        "data": {}
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/iota_getChainIdentifier": {
      "post": {
        "operationId": "iota_getChainIdentifier",
        "summary": "iota_getChainIdentifier",
        "description": "Return the first four bytes of the chain's genesis checkpoint digest.",
        "tags": [
          "Read"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "jsonrpc",
                  "id",
                  "method"
                ],
                "properties": {
                  "jsonrpc": {
                    "type": "string",
                    "enum": [
                      "2.0"
                    ],
                    "description": "JSON-RPC protocol version"
                  },
                  "id": {
                    "oneOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "string"
                      }
                    ],
                    "description": "Request identifier"
                  },
                  "method": {
                    "type": "string",
                    "enum": [
                      "iota_getChainIdentifier"
                    ],
                    "description": "The JSON-RPC method name"
                  },
                  "params": {
                    "type": "array",
                    "description": "Method parameters",
                    "items": {}
                  }
                }
              },
              "example": {
                "jsonrpc": "2.0",
                "id": 1,
                "method": "iota_getChainIdentifier",
                "params": []
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful JSON-RPC response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "jsonrpc": {
                      "type": "string",
                      "example": "2.0"
                    },
                    "id": {
                      "oneOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "string"
                        }
                      ]
                    },
                    "result": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "JSON-RPC error response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "jsonrpc": {
                      "type": "string"
                    },
                    "id": {
                      "oneOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "string"
                        }
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "integer"
                        },
                        "message": {
                          "type": "string"
                        },
                        "data": {}
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/iota_getCheckpoint": {
      "post": {
        "operationId": "iota_getCheckpoint",
        "summary": "iota_getCheckpoint",
        "description": "Return a checkpoint",
        "tags": [
          "Read"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "jsonrpc",
                  "id",
                  "method"
                ],
                "properties": {
                  "jsonrpc": {
                    "type": "string",
                    "enum": [
                      "2.0"
                    ],
                    "description": "JSON-RPC protocol version"
                  },
                  "id": {
                    "oneOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "string"
                      }
                    ],
                    "description": "Request identifier"
                  },
                  "method": {
                    "type": "string",
                    "enum": [
                      "iota_getCheckpoint"
                    ],
                    "description": "The JSON-RPC method name"
                  },
                  "params": {
                    "type": "array",
                    "description": "Method parameters",
                    "items": {}
                  }
                }
              },
              "example": {
                "jsonrpc": "2.0",
                "id": 1,
                "method": "iota_getCheckpoint",
                "params": []
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful JSON-RPC response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "jsonrpc": {
                      "type": "string",
                      "example": "2.0"
                    },
                    "id": {
                      "oneOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "string"
                        }
                      ]
                    },
                    "result": {
                      "$ref": "#/components/schemas/Checkpoint"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "JSON-RPC error response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "jsonrpc": {
                      "type": "string"
                    },
                    "id": {
                      "oneOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "string"
                        }
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "integer"
                        },
                        "message": {
                          "type": "string"
                        },
                        "data": {}
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/iota_getCheckpoints": {
      "post": {
        "operationId": "iota_getCheckpoints",
        "summary": "iota_getCheckpoints",
        "description": "Return paginated list of checkpoints",
        "tags": [
          "Read"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "jsonrpc",
                  "id",
                  "method"
                ],
                "properties": {
                  "jsonrpc": {
                    "type": "string",
                    "enum": [
                      "2.0"
                    ],
                    "description": "JSON-RPC protocol version"
                  },
                  "id": {
                    "oneOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "string"
                      }
                    ],
                    "description": "Request identifier"
                  },
                  "method": {
                    "type": "string",
                    "enum": [
                      "iota_getCheckpoints"
                    ],
                    "description": "The JSON-RPC method name"
                  },
                  "params": {
                    "type": "array",
                    "description": "Method parameters",
                    "items": {}
                  }
                }
              },
              "example": {
                "jsonrpc": "2.0",
                "id": 1,
                "method": "iota_getCheckpoints",
                "params": []
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful JSON-RPC response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "jsonrpc": {
                      "type": "string",
                      "example": "2.0"
                    },
                    "id": {
                      "oneOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "string"
                        }
                      ]
                    },
                    "result": {
                      "$ref": "#/components/schemas/Page_for_Checkpoint_and_String"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "JSON-RPC error response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "jsonrpc": {
                      "type": "string"
                    },
                    "id": {
                      "oneOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "string"
                        }
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "integer"
                        },
                        "message": {
                          "type": "string"
                        },
                        "data": {}
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/iota_getEvents": {
      "post": {
        "operationId": "iota_getEvents",
        "summary": "iota_getEvents",
        "description": "Return transaction events.",
        "tags": [
          "Read"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "jsonrpc",
                  "id",
                  "method"
                ],
                "properties": {
                  "jsonrpc": {
                    "type": "string",
                    "enum": [
                      "2.0"
                    ],
                    "description": "JSON-RPC protocol version"
                  },
                  "id": {
                    "oneOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "string"
                      }
                    ],
                    "description": "Request identifier"
                  },
                  "method": {
                    "type": "string",
                    "enum": [
                      "iota_getEvents"
                    ],
                    "description": "The JSON-RPC method name"
                  },
                  "params": {
                    "type": "array",
                    "description": "Method parameters",
                    "items": {}
                  }
                }
              },
              "example": {
                "jsonrpc": "2.0",
                "id": 1,
                "method": "iota_getEvents",
                "params": []
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful JSON-RPC response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "jsonrpc": {
                      "type": "string",
                      "example": "2.0"
                    },
                    "id": {
                      "oneOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "string"
                        }
                      ]
                    },
                    "result": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Event"
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "JSON-RPC error response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "jsonrpc": {
                      "type": "string"
                    },
                    "id": {
                      "oneOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "string"
                        }
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "integer"
                        },
                        "message": {
                          "type": "string"
                        },
                        "data": {}
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/iota_getLatestCheckpointSequenceNumber": {
      "post": {
        "operationId": "iota_getLatestCheckpointSequenceNumber",
        "summary": "iota_getLatestCheckpointSequenceNumber",
        "description": "Return the sequence number of the latest checkpoint that has been executed",
        "tags": [
          "Read"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "jsonrpc",
                  "id",
                  "method"
                ],
                "properties": {
                  "jsonrpc": {
                    "type": "string",
                    "enum": [
                      "2.0"
                    ],
                    "description": "JSON-RPC protocol version"
                  },
                  "id": {
                    "oneOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "string"
                      }
                    ],
                    "description": "Request identifier"
                  },
                  "method": {
                    "type": "string",
                    "enum": [
                      "iota_getLatestCheckpointSequenceNumber"
                    ],
                    "description": "The JSON-RPC method name"
                  },
                  "params": {
                    "type": "array",
                    "description": "Method parameters",
                    "items": {}
                  }
                }
              },
              "example": {
                "jsonrpc": "2.0",
                "id": 1,
                "method": "iota_getLatestCheckpointSequenceNumber",
                "params": []
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful JSON-RPC response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
          

# --- truncated at 32 KB (293 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/iota/refs/heads/main/openapi/iota-jsonrpc-openapi.json