For AI agents: an LLM-friendly Markdown version of every page is available by appending .md to its URL or by sending an Accept: text/markdown request header. The full documentation index is at https://www.ankr.com/docs/llms.txt
Skip to main content

IOTA — unsafe, iota (2/2)

API reference for IOTA. All methods ->

Part 2 of 2: 1 · 2

unsafe_requestWithdrawTimelockedStake​

Withdraws timelocked stake from a validator's staking pool.

Parameters​

  • id (integer; required): a request ID (example: 1).

  • jsonrpc (string; required): a JSON RPC spec used (example: 2.0).

  • method (string; required): a method used for the request.

  • params (array; required):

    • signer< IotaAddress > (required): the IOTA address of the transaction signer.
    • timelocked_staked_iota< ObjectID > (required): the object ID of the TimelockedStakedIota to be withdrawn.
    • gas< ObjectID > (required): the gas object to be used for paying transaction fees.
    • gas_budget< BigInt_for_uint64 > (required): the maximum amount of gas the transaction is allowed to consume. The transaction will fail if this budget is exceeded.

Returns​

TransactionBlockBytes< TransactionBlockBytes >
  • gas< [ObjectRef] > (required): the gas objects used to pay for the transaction execution.
  • inputObjects< [InputObjectKind] > (required): the input objects involved in the transaction, including the TimelockedStakedIota object and any supporting references.
  • txBytes< Base64 > (required): the transaction payload serialized in BCS format (without its type tag), and encoded as a base64 string.

Request example​

curl -X POST https://rpc.ankr.com/iota_mainnet/YOUR_ANKR_API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "method": "unsafe_requestWithdrawTimelockedStake",
    "params": [
      "0xSIGNER_ADDRESS",                   // signer<IotaAddress>
      "0xTIMELOCKED_STAKED_IOTA_OBJECT_ID", // timelocked_staked_iota<ObjectID>
      "0xGAS_OBJECT_ID",                    // gas<ObjectID>
      "5000000"                             // gas_budget<BigInt_for_uint64>
    ],
    "id": 1
  }'

Response example​

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "gas": [
      {
        "objectId": "0xGAS_OBJECT_ID",
        "version": 12345678,
        "digest": "0xGAS_OBJECT_DIGEST"
      }
    ],
    "inputObjects": [
      {
        "objectId": "0xTIMELOCKED_STAKED_IOTA_OBJECT_ID",
        "objectType": "staking::TimelockedStakedIota"
      }
    ],
    "txBytes": "BASE64_ENCODED_TRANSACTION_BYTES"
  }
}

unsafe_splitCoin​

Creates an unsigned transaction to split a coin into specified amounts.

Parameters​

  • id (integer; required): a request ID (example: 1).

  • jsonrpc (string; required): a JSON RPC spec used (example: 2.0).

  • method (string; required): a method used for the request.

  • params (array; required):

    • signer< IotaAddress > (required): the IOTA address of the transaction signer.
    • coin_object_id< ObjectID > (required): the object ID of the coin to be split.
    • split_amounts< [BigInt_for_uint64] > (required): a list of amounts to split from the coin. Each value represents a new coin to be created with that amount.
    • gas< ObjectID > (optional): the gas object to be used for paying transaction fees. If omitted, the node selects one from the signer's assets.
    • gas_budget< BigInt_for_uint64 > (required): the maximum gas allowed for this transaction. The transaction will fail if this limit is exceeded.

Returns​

TransactionBlockBytes< TransactionBlockBytes >
  • gas< [ObjectRef] > (required): the gas objects used to pay for the execution of the transaction.
  • inputObjects< [InputObjectKind] > (required): the objects involved in the transaction, including the coin being split and any other necessary references.
  • txBytes< Base64 > (required): the transaction payload serialized in BCS format (without its type tag), and encoded as a base64 string.

Request example​

curl -X POST https://rpc.ankr.com/iota_mainnet/YOUR_ANKR_API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "method": "unsafe_splitCoin",
    "params": [
      "0xSIGNER_ADDRESS",              // signer<IotaAddress>
      "0xCOIN_OBJECT_ID",             // coin_object_id<ObjectID>
      ["1000", "2000", "3000"],       // split_amounts<[BigInt_for_uint64]>
      "0xOPTIONAL_GAS_OBJECT_ID",     // gas<ObjectID> (optional, can be null)
      "5000000"                       // gas_budget<BigInt_for_uint64>
    ],
    "id": 1
  }'

Response example​

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "gas": [
      {
        "objectId": "0xGAS_OBJECT_ID",
        "version": 12345678,
        "digest": "0xGAS_OBJECT_DIGEST"
      }
    ],
    "inputObjects": [
      {
        "objectId": "0xCOIN_OBJECT_ID",
        "objectType": "coin::Coin<0x2::iota::IOTA>"
      }
    ],
    "txBytes": "BASE64_ENCODED_TRANSACTION_BYTES"
  }
}

unsafe_splitCoinEqual​

Creates an unsigned transaction to split a coin into equal parts.

Parameters​

  • id (integer; required): a request ID (example: 1).

  • jsonrpc (string; required): a JSON RPC spec used (example: 2.0).

  • method (string; required): a method used for the request.

  • params (array; required):

    • signer< IotaAddress > (required): the IOTA address of the transaction signer.
    • coin_object_id< ObjectID > (required): the object ID of the coin to be split.
    • split_count< BigInt_for_uint64 > (required): the number of equally sized coins to create from the original coin. The total coin value will be evenly divided among them.
    • gas< ObjectID > (optional): the gas object to be used for transaction fee payment. If omitted, the node will select one automatically from the signer’s holdings.
    • gas_budget< BigInt_for_uint64 > (required): the gas budget for the transaction. The transaction fails if this amount is exceeded during execution.

Returns​

TransactionBlockBytes< TransactionBlockBytes >
  • gas< [ObjectRef] > (required): the gas objects used to pay for the transaction execution.
  • inputObjects< [InputObjectKind] > (required): the input objects involved in the transaction, including the coin being split.
  • txBytes< Base64 > (required): the transaction payload serialized using BCS (without its type tag) and encoded as a base64 string.

Request example​

curl -X POST https://rpc.ankr.com/iota_mainnet/YOUR_ANKR_API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "method": "unsafe_splitCoinEqual",
    "params": [
      "0xSIGNER_ADDRESS",          // signer<IotaAddress>
      "0xCOIN_OBJECT_ID",         // coin_object_id<ObjectID>
      "3",                         // split_count<BigInt_for_uint64>
      "0xOPTIONAL_GAS_OBJECT_ID", // gas<ObjectID> (optional, can be null)
      "5000000"                   // gas_budget<BigInt_for_uint64>
    ],
    "id": 1
  }'

Response example​

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "gas": [
      {
        "objectId": "0xGAS_OBJECT_ID",
        "version": 12345678,
        "digest": "0xGAS_OBJECT_DIGEST"
      }
    ],
    "inputObjects": [
      {
        "objectId": "0xCOIN_OBJECT_ID",
        "objectType": "coin::Coin<0x2::iota::IOTA>"
      }
    ],
    "txBytes": "BASE64_ENCODED_TRANSACTION_BYTES"
  }
}

unsafe_transferIota​

Creates an unsigned transaction to transfer IOTA coins.

Creates an unsigned transaction to send IOTA coin object to an IOTA address. The IOTA object is also used as the gas object.

Parameters​

  • id (integer; required): a request ID (example: 1).

  • jsonrpc (string; required): a JSON RPC spec used (example: 2.0).

  • method (string; required): a method used for the request.

  • params (array; required):

    • signer< IotaAddress > (required): the IOTA address of the transaction signer.
    • iota_object_id< ObjectID > (required): the object ID of the IOTA coin to be used in the transaction.
    • gas_budget< BigInt_for_uint64 > (required): the gas budget for the transaction. The transaction will fail if gas usage exceeds this amount.
    • recipient< IotaAddress > (required): the IOTA address of the recipient who will receive the transferred amount.
    • amount< BigInt_for_uint64 > (optional): the amount of IOTA to be split from the original coin and transferred to the recipient. If omitted, the entire coin may be transferred.

Returns​

TransactionBlockBytes< TransactionBlockBytes >
  • gas< [ObjectRef] > (required): the gas objects used to pay for executing the transaction.
  • inputObjects< [InputObjectKind] > (required): the input objects involved in the transaction, including the IOTA coin and any other dependencies.
  • txBytes< Base64 > (required): the transaction data, serialized using BCS (without its type tag) and encoded as a base64 string.

Request example​

curl -X POST https://rpc.ankr.com/iota_mainnet/YOUR_ANKR_API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "method": "unsafe_transferIota",
    "params": [
      "0xSIGNER_ADDRESS",         // signer<IotaAddress>
      "0xIOTA_OBJECT_ID",         // iota_object_id<ObjectID>
      "5000000",                  // gas_budget<BigInt_for_uint64>
      "0xRECIPIENT_ADDRESS",      // recipient<IotaAddress>
      "100000000"                 // amount<BigInt_for_uint64> (optional)
    ],
    "id": 1
  }'

Response example​

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "gas": [
      {
        "objectId": "0xGAS_OBJECT_ID",
        "version": 12345678,
        "digest": "0xGAS_OBJECT_DIGEST"
      }
    ],
    "inputObjects": [
      {
        "objectId": "0xIOTA_OBJECT_ID",
        "objectType": "coin::Coin<0x2::iota::IOTA>"
      }
    ],
    "txBytes": "BASE64_ENCODED_TRANSACTION_BYTES"
  }
}

unsafe_transferObject​

Creates an unsigned transaction to transfer an on-chain object.

Creates an unsigned transaction to transfer an object from one address to another. The object's type must allow public transfers.

Parameters​

  • id (integer; required): a request ID (example: 1).

  • jsonrpc (string; required): a JSON RPC spec used (example: 2.0).

  • method (string; required): a method used for the request.

  • params (array; required):

    • signer< IotaAddress > (required): the IOTA address of the transaction signer.
    • object_id< ObjectID > (required): the object ID of the item to be transferred.
    • gas< ObjectID > (optional): the gas object to be used for paying transaction fees. If not specified, the node selects one automatically from the signer's assets.
    • gas_budget< BigInt_for_uint64 > (required): the maximum gas allowed for this transaction. The transaction will fail if this amount is exceeded.
    • recipient< IotaAddress > (required): the IOTA address of the recipient who will receive the transferred object.

Returns​

TransactionBlockBytes< TransactionBlockBytes >
  • gas< [ObjectRef] > (required): the gas objects used to pay for executing the transaction.
  • inputObjects< [InputObjectKind] > (required): the input objects involved in the transaction, including the object being transferred and any related dependencies.
  • txBytes< Base64 > (required): the transaction payload serialized using BCS (without its type tag) and encoded as a base64 string.

Request example​

curl -X POST https://rpc.ankr.com/iota_mainnet/YOUR_ANKR_API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "method": "unsafe_transferObject",
    "params": [
      "0xSIGNER_ADDRESS",      // signer<IotaAddress>
      "0xOBJECT_ID",           // object_id<ObjectID>
      "0xOPTIONAL_GAS_ID",     // gas<ObjectID> (optional, can be null)
      "5000000",               // gas_budget<BigInt_for_uint64>
      "0xRECIPIENT_ADDRESS"    // recipient<IotaAddress>
    ],
    "id": 1
  }'

Response example​

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "gas": [
      {
        "objectId": "0xGAS_OBJECT_ID",
        "version": 12345678,
        "digest": "0xGAS_OBJECT_DIGEST"
      }
    ],
    "inputObjects": [
      {
        "objectId": "0xOBJECT_ID",
        "objectType": "example::CustomObjectType"
      }
    ],
    "txBytes": "BASE64_ENCODED_TRANSACTION_BYTES"
  }
}

iota_devInspectTransactionBlock​

Simulates a transaction block for debugging and inspection.

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.

Parameters​

  • id (integer; required): a request ID (example: 1).

  • jsonrpc (string; required): a JSON RPC spec used (example: 2.0).

  • method (string; required): a method used for the request.

  • params (array; required):

    • sender_address< IotaAddress > (required): the IOTA address initiating the dev inspect call.
    • tx_bytes< Base64 > (required): the BCS-encoded TransactionKind (not TransactionData). This includes only the transaction logic without gasBudget and gasPrice.
    • gas_price< BigInt_for_uint64 > (optional): the reference gas price to use for calculating gas usage. No actual gas is charged. If omitted, the system will use the default reference gas price.
    • epoch< BigInt_for_uint64 > (optional): the epoch during which to simulate the call. If not provided, it will default to the current epoch from the latest system state.
    • additional_args< DevInspectArgs > (optional): additional simulation configuration, including: gas_budget, gas_objects, gas_sponsor, skip_checks.

Returns​

DevInspectResults< DevInspectResults >
  • effects< TransactionBlockEffects > (required): the simulated summary of effects that would likely occur if the transaction were executed. Note: not all dev-inspected transactions are valid for execution.
  • error< [string, null] > (optional): any execution error encountered during simulation, if applicable.
  • events< [Event] > (required): the list of events that would likely be emitted by the transaction if it were run.
  • rawEffects< [string] > (optional): raw data representation of the transaction effects that were simulated.
  • rawTxnData< [string] > (optional): raw data representation of the transaction itself used in the dev inspection.
  • results< [IotaExecutionResult, null] > (optional): execution results from running the transaction, including any return values or outputs from function calls.

Request example​

curl -X POST https://rpc.ankr.com/iota_mainnet/YOUR_ANKR_API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "method": "iota_devInspectTransactionBlock",
    "params": [
      "0x94f1a597b4e8f709a396f7f6b1482bdcd65a673d111e49286c527fab7c2d0961",  // sender_address<IotaAddress>
      "BASE64_ENCODED_TX_BYTES",                                            // tx_bytes<Base64>
      "1",                                                                  // gas_price<BigInt_for_uint64> (optional)
      "1000",                                                               // epoch<BigInt_for_uint64> (optional)
      {
        "gas_budget": "1000000",                                            // gas_budget<BigInt_for_uint64> (optional)
        "gas_objects": ["0xGAS_OBJECT_ID"],                                 // gas_objects<[ObjectID]> (optional)
        "gas_sponsor": "0xSPONSOR_ADDRESS",                                 // gas_sponsor<IotaAddress> (optional)
        "skip_checks": true                                                 // skip_checks<boolean> (optional)
      }
    ],
    "id": 1
  }'

Response example​

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "effects": {
      // Summary of effects that would likely occur if the transaction were executed
    },
    "error": null,
    "events": [
      // List of events that would likely be emitted by the transaction
    ],
    "rawEffects": [
      // Raw data representation of the transaction effects
    ],
    "rawTxnData": [
      // Raw data representation of the transaction itself
    ],
    "results": [
      // Execution results from running the transaction, including return values
    ]
  }
}

iota_dryRunTransactionBlock​

Simulates execution of a transaction block without committing it.

Returns transaction execution effects including the gas cost summary, while the effects are not committed to the chain.

Parameters​

  • id (integer; required): a request ID (example: 1).

  • jsonrpc (string; required): a JSON RPC spec used (example: 2.0).

  • method (string; required): a method used for the request.

  • params (array; required):

    • tx_bytes< Base64 > (required): the transaction payload encoded as a base64 string. This must be the BCS-encoded TransactionKind (not TransactionData), meaning it contains only the logic of the transaction without metadata such as gasBudget or gasPrice.

Returns​

DryRunTransactionBlockResponse< DryRunTransactionBlockResponse >
  • balanceChanges< [BalanceChange] > (required): a list of balance changes resulting from the execution of the transaction.
  • effects< TransactionBlockEffects > (required): summary of transaction effects, including created, mutated, and deleted objects, along with gas usage and status.
  • events< [Event] > (required): events emitted during the transaction execution.
  • input< TransactionBlockData > (required): the transaction input data, including sender, gas settings, and execution logic.
  • objectChanges< [ObjectChange] > (required): a list of changes made to on-chain objects, including object creation, mutation, and deletion.

Request example​

curl -X POST https://rpc.ankr.com/iota_mainnet/YOUR_ANKR_API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "method": "iota_dryRunTransactionBlock",
    "params": [
      "BASE64_ENCODED_TX_BYTES",  // tx_bytes<Base64>
      {
        "sender": "0xSENDER_ADDRESS",       // sender<IotaAddress>
        "gasBudget": "1000000",             // gas_budget<BigInt_for_uint64>
        "gasPrice": "1"                     // gas_price<BigInt_for_uint64> (optional)
      },
      false  // skipChecks<boolean> (optional)
    ],
    "id": 1
  }'

Response example​

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "balanceChanges": [
      {
        "owner": "0xSENDER_ADDRESS",
        "coinType": "0x2::iota::IOTA",
        "amount": "-100000"
      },
      {
        "owner": "0xRECIPIENT_ADDRESS",
        "coinType": "0x2::iota::IOTA",
        "amount": "100000"
      }
    ],
    "effects": {
      "status": "success",
      "created": [],
      "mutated": [],
      "deleted": [],
      "gasUsed": "50000"
    },
    "events": [
      {
        "type": "0x2::iota::TransferEvent",
        "sender": "0xSENDER_ADDRESS",
        "recipient": "0xRECIPIENT_ADDRESS",
        "amount": "100000"
      }
    ],
    "input": {
      "sender": "0xSENDER_ADDRESS",
      "gasBudget": "1000000",
      "gasPrice": "1",
      "kind": {
        "Transfer": {
          "recipient": "0xRECIPIENT_ADDRESS",
          "amount": "100000"
        }
      }
    },
    "objectChanges": [],
    "error": null
  }
}

iota_executeTransactionBlock​

Executes and commits a transaction block to the network.

Executes the transaction and optionally waits for the result. Supported request types:

  1. WaitForEffectsCert – Waits for the TransactionEffectsCert before returning the response. This mode serves as a proxy for transaction finality.

  2. WaitForLocalExecution – Waits for the TransactionEffectsCert and ensures the node has executed the transaction locally before responding. This guarantees that the node is aware of the transaction for subsequent client queries. If the node fails to execute the transaction in time, the response includes a false flag indicating the failure.

If neither is specified, the default behavior is WaitForEffectsCert—unless options.show_events or options.show_effects is set to true, in which case WaitForLocalExecution is used.

Parameters​

  • id (integer; required): a request ID (example: 1).

  • jsonrpc (string; required): a JSON RPC spec used (example: 2.0).

  • method (string; required): a method used for the request.

  • params (array; required):

    • tx_bytes< Base64 > (required): BCS-serialized transaction data bytes (excluding the type tag), encoded as a base64 string.
    • signatures< [Base64] > (required): a list of signatures, each encoded as base64. Each entry must be in the format: flag || signature || public_key. The signatures must be committed to the intent message derived from the transaction data.
    • options< TransactionBlockResponseOptions > (optional): configuration options to specify which parts of the transaction response should be returned (e.g., events, effects, inputs).
    • request_type< ExecuteTransactionRequestType > (optional): the type of request execution behavior. If not provided, it will be inferred from options. Default is WaitForEffectsCert.

Returns​

IotaTransactionBlockResponse< TransactionBlockResponse >
  • balanceChanges< [BalanceChange, null] > (optional): a list of balance changes resulting from the execution of the transaction.
  • checkpoint< BigInt_for_uint64 | null > (optional): the checkpoint number at which this transaction was finalized. Only available in read APIs, not execution endpoints.
  • confirmedLocalExecution< [boolean, null] > (optional): indicates whether the node has successfully executed the transaction locally.
  • digest< TransactionDigest > (required): the unique digest of the executed transaction.
  • effects< TransactionBlockEffects | null > (optional): the effects of the transaction, including status, object mutations, and gas usage.
  • errors< [string] > (optional): a list of errors encountered during transaction execution, if any.
  • events< [Event, null] > (optional): a list of events emitted during the transaction execution.
  • objectChanges< [ObjectChange, null] > (optional): a list of changes to on-chain objects, such as creations, deletions, or mutations.
  • rawEffects< [string] > (optional): the raw, serialized representation of transaction effects.
  • rawTransaction< Base64 > (optional): BCS-encoded SenderSignedData representing the transaction, including input object references. Will be empty if options.show_raw_transaction is false.
  • timestampMs< BigInt_for_uint64 | null > (optional): the Unix timestamp (in milliseconds) when the transaction was finalized.
  • transaction< TransactionBlock | null > (optional): the input data of the transaction, including sender, gas settings, and logic.

Request example​

curl -X POST https://rpc.ankr.com/iota_mainnet/YOUR_ANKR_API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "method": "iota_executeTransactionBlock",
    "params": [
      "BASE64_ENCODED_TX_BYTES",           // tx_bytes
      [
        "BASE64_ENCODED_SIGNATURE_1",      // signatures[]
        "BASE64_ENCODED_SIGNATURE_2"
      ],
      {
        "show_input": true,
        "show_effects": true,
        "show_events": true,
        "show_object_changes": true,
        "show_raw_transaction": true,
        "show_balance_changes": true
      },
      "WaitForLocalExecution"             // request_type (optional)
    ],
    "id": 1
  }'

Response example​

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "digest": "9XZBtYjprrsNzL4QXHj1SmttfAWhu7A8iTfbbJcYkHQx",
    "transaction": {
      "sender": "0x1a2b3c...abcd",
      "gasBudget": "1000000",
      "kind": {
        "MoveCall": {
          "package": "0x2",
          "module": "pay",
          "function": "split",
          "arguments": [ ... ]
        }
      }
    },
    "effects": {
      "status": "success",
      "gasUsed": "50000",
      "created": [ ... ],
      "mutated": [ ... ],
      "deleted": [ ... ]
    },
    "events": [
      {
        "type": "0x2::coin::SplitEvent",
        "sender": "0x1a2b3c...abcd",
        "details": {
          "amount": "500000",
          "recipient": "0x4d5e6f...beef"
        }
      }
    ],
    "balanceChanges": [
      {
        "owner": "0x1a2b3c...abcd",
        "coinType": "0x2::iota::IOTA",
        "amount": "-500000"
      },
      {
        "owner": "0x4d5e6f...beef",
        "coinType": "0x2::iota::IOTA",
        "amount": "500000"
      }
    ],
    "objectChanges": [ ... ],
    "rawTransaction": "BASE64_ENCODED_SENDER_SIGNED_DATA",
    "timestampMs": "1747234567890",
    "confirmedLocalExecution": true
  }
}