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 (1/2)

API reference for IOTA. All methods ->

Part 1 of 2: 1 · 2

unsafe_pay​

Creates a transaction to transfer coins to multiple recipients.

Sends Coin<T> to a list of recipient addresses, where T can be any supported coin type. The amounts must correspond to each recipient in the list. The object specified in the gas field will be used to pay the transaction fee. The gas object must not be included in the input_coins. If no gas object is provided, the RPC server will automatically select one.

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.
    • input_coins< [ObjectID] > (required): the list of IOTA coin object IDs to be used for this transaction.
    • recipients< [IotaAddress] > (required): the list of recipient addresses. The length must match the amounts array.
    • amounts< [BigInt_for_uint64] > (required): the list of amounts to send to each corresponding recipient.
    • gas< ObjectID > (optional): the gas object used to pay for transaction execution. If not provided, the node will automatically select one from the signer's assets.
    • gas_budget< BigInt_for_uint64 > (required): the gas limit for the transaction. The transaction will fail if this limit is exceeded.

Returns​

TransactionBlockBytes< TransactionBlockBytes >
  • gas< [ObjectRef] > (required): the gas objects that will be used in the transaction.
  • inputObjects< [InputObjectKind] > (required): the input objects that are referenced and consumed during transaction execution.
  • txBytes< Base64 > (required): the BCS-encoded transaction data (excluding the type tag), represented 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_pay",
    "params": [
      "0xSIGNER_ADDRESS",               // IOTA address of the sender
      [
        "0xINPUT_COIN_1",               // Coin object IDs to be used
        "0xINPUT_COIN_2"
      ],
      [
        "0xRECIPIENT_ADDRESS_1",        // Recipient addresses
        "0xRECIPIENT_ADDRESS_2"
      ],
      [
        "1000000",                      // Amounts to transfer (must match recipient count)
        "2500000"
      ],
      "0xOPTIONAL_GAS_OBJECT_ID",       // Optional: gas object (omit or set to null to auto-select)
      "5000000"                         // Gas budget (as string)
    ],
    "id": 1
  }'

Response example​

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "digest": "0xTRANSACTION_DIGEST",
    "effects": {
      "status": {
        "status": "success"
      },
      "executedEpoch": "123",
      "gasUsed": {
        "computationCost": "1000000",
        "storageCost": "80000",
        "storageRebate": "75000",
        "nonRefundableStorageFee": "0"
      },
      "mutated": [
        {
          "owner": {
            "AddressOwner": "0xSIGNER_ADDRESS"
          },
          "reference": {
            "objectId": "0xPRIMARY_COIN_OBJECT_ID",
            "version": 12345678,
            "digest": "0xUPDATED_OBJECT_DIGEST"
          }
        }
      ],
      "deleted": [
        {
          "objectId": "0xMERGED_COIN_OBJECT_ID",
          "version": 12345678,
          "digest": "0xDELETED_OBJECT_DIGEST"
        }
      ],
      "gasObject": {
        "owner": {
          "AddressOwner": "0xSIGNER_ADDRESS"
        },
        "reference": {
          "objectId": "0xGAS_OBJECT_ID",
          "version": 12345678,
          "digest": "0xGAS_OBJECT_DIGEST"
        }
      }
    },
    "events": [],
    "timestampMs": "1690000000000",
    "checkpoint": "1234567"
  }
}

unsafe_payAllIota​

Creates a transaction to transfer all IOTA coins to a single recipient.

Sends all IOTA from multiple coin objects to a single recipient. This method supports IOTA coin only and does not require a separate gas coin object.

The pay_all_iota operation performs the following steps:

  1. Aggregates the total IOTA from all input coins and consolidates it into the first input coin.
  2. Transfers the updated first coin to the recipient and uses it as the gas object for the transaction.
  3. After execution, the first input coin holds the remaining balance: sum(input_coins) - actual_gas_cost.
  4. All other input coins (except the first) are deleted.

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.
    • input_coins< [ObjectID] > (required): the IOTA coin object IDs to be used in the transaction, including the coin that will be used to pay for gas.
    • recipient< IotaAddress > (required): the address to receive the consolidated IOTA.
    • gas_budget< BigInt_for_uint64 > (required): the maximum amount of gas allowed for the transaction. The transaction will fail if this budget is exceeded.

Returns​

TransactionBlockBytes< TransactionBlockBytes >
  • gas< [ObjectRef] > (required): the gas objects used in the transaction execution.
  • inputObjects< [InputObjectKind] > (required): the input objects that are referenced and processed during the transaction.
  • txBytes< Base64 > (required): the BCS-encoded transaction data, without its type tag, represented as a base64-encoded 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_payAllIota",
    "params": [
      "0xSIGNER_ADDRESS",             // IOTA address of the sender
      [
        "0xINPUT_COIN_ID_1",          // Input coins (must include coin used for gas)
        "0xINPUT_COIN_ID_2"
      ],
      "0xRECIPIENT_ADDRESS",          // Recipient address
      "5000000"                       // Gas budget (as string)
    ],
    "id": 1
  }'

Response example​

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "gas": [
      {
        "objectId": "0xGAS_OBJECT_ID",            // gas object used
        "version": 12345678,
        "digest": "0xGAS_OBJECT_DIGEST"
      }
    ],
    "inputObjects": [
      {
        "objectId": "0xINPUT_COIN_ID_1",          // first coin used and retained
        "objectType": "coin::Coin<0x2::iota::IOTA>"
      },
      {
        "objectId": "0xINPUT_COIN_ID_2",          // coin that was merged and deleted
        "objectType": "coin::Coin<0x2::iota::IOTA>"
      }
    ],
    "txBytes": "BASE64_ENCODED_TRANSACTION_DATA" // base64-encoded BCS transaction bytes
  }
}

unsafe_payIota​

Creates a transaction to transfer IOTA coins to multiple recipients.

Sends IOTA coins to a list of recipient addresses based on a corresponding list of amounts. This method supports IOTA coin only and does not require a separate gas coin object.

The pay_iota operation performs the following:

  1. Debits each input_coin to create new coin objects corresponding to the specified amounts and assigns them to the matching recipients.
  2. Accumulates any remaining IOTA from the input coins into the first input coin and uses it as the gas coin object.
  3. After execution, the balance of the first input coin is: sum(input_coins) - sum(amounts) - actual_gas_cost.
  4. All other input coins, except the first one, are deleted.

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.
    • input_coins< [ObjectID] > (required): the list of IOTA coin object IDs to be used in this transaction, including the coin that will cover gas fees.
    • recipients< [IotaAddress] > (required): the list of recipient addresses. The length must match the amounts list.
    • amounts< [BigInt_for_uint64] > (required): the list of amounts to transfer to each corresponding recipient, in the same order as recipients.
    • gas_budget< BigInt_for_uint64 > (required): the maximum gas allowed for the transaction. The transaction fails 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 referenced and consumed during the transaction.
  • txBytes< Base64 > (required): the BCS-encoded transaction data (without a type tag), represented as a base64-encoded 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_payIota",
    "params": [
      "0xSIGNER_ADDRESS",               // IOTA address of the sender
      [
        "0xINPUT_COIN_ID_1",            // IOTA coin object IDs (including the one for gas)
        "0xINPUT_COIN_ID_2"
      ],
      [
        "0xRECIPIENT_ADDRESS_1",        // Recipient addresses
        "0xRECIPIENT_ADDRESS_2"
      ],
      [
        "1000000",                      // Amounts to send (must match recipients)
        "2500000"
      ],
      "5000000"                         // Gas budget (as string)
    ],
    "id": 1
  }'

Response example​

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "gas": [
      {
        "objectId": "0xGAS_OBJECT_ID",            // gas object used
        "version": 12345678,
        "digest": "0xGAS_OBJECT_DIGEST"
      }
    ],
    "inputObjects": [
      {
        "objectId": "0xINPUT_COIN_ID_1",          // first coin retained and used for gas
        "objectType": "coin::Coin<0x2::iota::IOTA>"
      },
      {
        "objectId": "0xINPUT_COIN_ID_2",          // coin that was consumed
        "objectType": "coin::Coin<0x2::iota::IOTA>"
      }
    ],
    "txBytes": "BASE64_ENCODED_TRANSACTION_DATA" // base64-encoded BCS transaction bytes
  }
}

unsafe_publish​

Creates an unsigned transaction to publish Move modules.

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< IotaAddress > (required): the IOTA address of the transaction signer.
    • compiled_modules< [Base64] > (required): the compiled Move modules, encoded in base64 format.
    • dependencies< [ObjectID] > (required): a list of object IDs representing the transitive dependencies required by the Move package.
    • gas< ObjectID > (optional): the gas coin object to use for paying transaction fees. If not specified, the node will auto-select one from the sender's assets.
    • gas_budget< BigInt_for_uint64 > (required): the gas budget for the transaction. The transaction will fail if gas consumption exceeds this value.

Returns​

TransactionBlockBytes< TransactionBlockBytes >
  • gas< [ObjectRef] > (required): the gas objects used to pay for the transaction execution.
  • inputObjects< [InputObjectKind] > (required): the input objects that are referenced, mutated, or consumed during the transaction.
  • 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_publish",
    "params": [
      "0xSIGNER_ADDRESS",                   // sender<IotaAddress>
      [
        "BASE64_COMPILED_MODULE_1",         // compiled_modules<[Base64]>
        "BASE64_COMPILED_MODULE_2"
      ],
      [
        "0xDEPENDENCY_OBJECT_ID_1",         // dependencies<[ObjectID]>
        "0xDEPENDENCY_OBJECT_ID_2"
      ],
      "0xOPTIONAL_GAS_OBJECT_ID",           // gas<ObjectID> (optional)
      "10000000"                            // gas_budget<BigInt_for_uint64>
    ],
    "id": 1
  }'

Response example​

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "gas": [
      {
        "objectId": "0xGAS_OBJECT_ID",       // Gas object used
        "version": 12345678,
        "digest": "0xGAS_OBJECT_DIGEST"
      }
    ],
    "inputObjects": [
      {
        "objectId": "0xSIGNER_ADDRESS",
        "objectType": "0x2::account::Account"
      },
      {
        "objectId": "0xDEPENDENCY_OBJECT_ID_1",
        "objectType": "0x1::move_stdlib::Module"
      }
    ],
    "txBytes": "BASE64_ENCODED_TRANSACTION_BYTES"
  }
}

unsafe_requestAddStake​

Creates a request to add stake.

Adds stake to a validator's staking pool using multiple coins and amount.

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.
    • coins< [ObjectID] > (required): the list of Coin<IOTA> object IDs to be staked in this transaction.
    • amount< BigInt_for_uint64 > (optional): the amount to stake. If omitted, the total balance from the provided coin objects is used.
    • validator< IotaAddress > (required): the IOTA address of the validator to which the stake is delegated.
    • gas< ObjectID > (optional): the gas object used to pay transaction fees. If not specified, one will be selected automatically from the signer's assets.
    • gas_budget< BigInt_for_uint64 > (required): the maximum amount of gas allocated for the transaction. The transaction fails if this budget is exceeded.

Returns​

TransactionBlockBytes< TransactionBlockBytes >
  • gas< [ObjectRef] > (required): the gas objects that will be used to pay for the transaction.
  • inputObjects< [InputObjectKind] > (required): the input objects referenced in the transaction, including coins and validator-related inputs.
  • txBytes< Base64 > (required): the transaction data serialized in BCS format (excluding the 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_requestAddStake",
    "params": [
      "0xSIGNER_ADDRESS",                 // signer<IotaAddress>
      [
        "0xCOIN_OBJECT_ID_1",             // coins<[ObjectID]>
        "0xCOIN_OBJECT_ID_2"
      ],
      "1000000000",                       // amount<BigInt_for_uint64> (optional, can be null)
      "0xVALIDATOR_ADDRESS",             // validator<IotaAddress>
      "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_1",
        "objectType": "coin::Coin<0x2::iota::IOTA>"
      },
      {
        "objectId": "0xCOIN_OBJECT_ID_2",
        "objectType": "coin::Coin<0x2::iota::IOTA>"
      },
      {
        "objectId": "0xVALIDATOR_ADDRESS",
        "objectType": "staking::Validator"
      }
    ],
    "txBytes": "BASE64_ENCODED_TRANSACTION_BYTES"
  }
}

unsafe_requestAddTimelockedStake​

Adds a timelocked stake.

Adds timelocked stake to a validator's staking pool using multiple balances and amount.

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.
    • locked_balance< ObjectID > (required): the object ID of the TimeLock<Balance<IOTA>> that will be staked.
    • validator< IotaAddress > (required): the IOTA address of the validator to whom the stake is being delegated.
    • gas< ObjectID > (required): the gas object used to pay for the transaction. This must be explicitly provided.
    • gas_budget< BigInt_for_uint64 > (required): the gas budget for the transaction. The transaction will fail if the actual gas used exceeds this value.

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, such as the locked balance object and validator address.
  • txBytes< Base64 > (required): the transaction data, 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_requestAddTimelockedStake",
    "params": [
      "0xSIGNER_ADDRESS",               // signer<IotaAddress>
      "0xLOCKED_BALANCE_OBJECT_ID",    // locked_balance<ObjectID>
      "0xVALIDATOR_ADDRESS",           // validator<IotaAddress>
      "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": "0xLOCKED_BALANCE_OBJECT_ID",
        "objectType": "timelock::TimeLock<coin::Coin<0x2::iota::IOTA>>"
      },
      {
        "objectId": "0xVALIDATOR_ADDRESS",
        "objectType": "staking::Validator"
      }
    ],
    "txBytes": "BASE64_ENCODED_TRANSACTION_BYTES"
  }
}

unsafe_requestWithdrawStake​

Withdraws 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.
    • staked_iota< ObjectID > (required): the object ID of the StakedIota that is to be withdrawn.
    • gas< ObjectID > (optional): the gas object to be used for transaction fees. If not specified, the node will automatically select one from the signer's holdings.
    • gas_budget< BigInt_for_uint64 > (required): the maximum gas allowed for the transaction. The transaction will fail if gas consumption exceeds this value.

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 staked IOTA object and any additional references.
  • txBytes< Base64 > (required): the transaction payload, serialized in BCS format (excluding 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_requestWithdrawStake",
    "params": [
      "0xSIGNER_ADDRESS",             // signer<IotaAddress>
      "0xSTAKED_IOTA_OBJECT_ID",     // staked_iota<ObjectID>
      "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": "0xSTAKED_IOTA_OBJECT_ID",
        "objectType": "staking::StakedIota"
      }
    ],
    "txBytes": "BASE64_ENCODED_TRANSACTION_BYTES"
  }
}