Skip to content

transactions.mdx

Latest commit

 

History

History
1050 lines (817 loc) · 33.7 KB

transactions.mdx

File metadata and controls

1050 lines (817 loc) · 33.7 KB
id transactions
title Transactions 
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

This component of the REST API allows one to send (broadcast) Transactions to the Blockchain and query information about them.

POST Send Transaction {#send-transaction}

https://gateway.multiversx.com/transaction/send

This endpoint allows one to send a signed Transaction to the Blockchain.

<Tabs defaultValue="Request" values={[ {label: 'Request', value: 'Request'}, {label: 'Response', value: 'Response'}, ]}>

Body Parameters

Param Required Type Description
nonce REQUIRED number The Nonce of the Sender.
value REQUIRED string The Value to transfer, as a string representation of a Big Integer (can be "0").
receiver REQUIRED string The Address (bech32) of the Receiver.
sender REQUIRED string The Address (bech32) of the Sender.
guardian OPTIONAL string The Address (bech32) of the Guardian.
senderUsername OPTIONAL string The base64 string representation of the Sender's username.
receiverUsername OPTIONAL string The base64 string representation of the Receiver's username.
gasPrice REQUIRED number The desired Gas Price (per Gas Unit).
gasLimit REQUIRED number The maximum amount of Gas Units to consume.
data OPTIONAL string The base64 string representation of the Transaction's message (data).
signature REQUIRED string The Signature (hex-encoded) of the Transaction.
guardianSignature OPTIONAL string The Guardian's Signature (hex-encoded) of the Transaction.
chainID REQUIRED string The Chain identifier.
version REQUIRED number The Version of the Transaction (e.g. 1).
options OPTIONAL number The Options of the Transaction (e.g. 1).

🟢 200: OK

Transaction sent with success. A Transaction Hash is returned.

{
  "data": {
    "txHash": "6c41c71946b5b428c2cfb560e3ea425f8a00345de4bb2eb1b784387790914277"
  },
  "error": "",
  "code": "successful"
}

🔴 400: Bad request

Invalid Transaction signature.

{
  "data": null,
  "error": "transaction generation failed: ed25519: invalid signature",
  "code": "bad_request"
}

:::caution For Nodes (Observers or Validators with the HTTP API enabled), this endpoint only accepts transactions whose sender is in the Node's Shard. :::

Here's an example of a request:

POST https://gateway.multiversx.com/transaction/send HTTP/1.1
Content-Type: application/json
{
    "nonce": 42,
    "value": "100000000000000000",
    "receiver": "erd1cux02zersde0l7hhklzhywcxk4u9n4py5tdxyx7vrvhnza2r4gmq4vw35r",
    "sender": "erd1njqj2zggfup4nl83x0nfgqjkjserm7mjyxdx5vzkm8k0gkh40ezqtfz9lg",
    "gasPrice": 1000000000,
    "gasLimit": 70000,
    "data": "Zm9vZCBmb3IgY2F0cw==", #base64 representation of "food for cats"
    "signature": "93207c579bf57be03add632b0e1624a73576eeda8a1687e0fa286f03eb1a17ffb125ccdb008a264c402f074a360442c7a034e237679322f62268b614e926d10f",
    "chainId": "1",
    "version": 1
}

:::info More information about sending a guarded transaction can be found here: Guarded Accounts :::

POST Send Multiple Transactions {#send-multiple-transactions}

https://gateway.multiversx.com/transaction/send-multiple

This endpoint allows one to send a bulk of Transactions to the Blockchain.

<Tabs defaultValue="Request" values={[ {label: 'Request', value: 'Request'}, {label: 'Response', value: 'Response'}, ]}>

Body Parameters

Array of:

Param Required Type Description
nonce REQUIRED number The Nonce of the Sender.
value REQUIRED string The Value to transfer, as a string representation of a Big Integer (can be "0").
receiver REQUIRED string The Address (bech32) of the Receiver.
sender REQUIRED string The Address (bech32) of the Sender.
senderUsername OPTIONAL string The base64 string representation of the Sender's username.
receiverUsername OPTIONAL string The base64 string representation of the Receiver's username.
gasPrice REQUIRED number The desired Gas Price (per Gas Unit).
gasLimit REQUIRED number The maximum amount of Gas Units to consume.
data OPTIONAL string The base64 string representation of the Transaction's message (data).
signature REQUIRED string The Signature (hex-encoded) of the Transaction.
chainID REQUIRED string The Chain identifier.
version REQUIRED number The Version of the Transaction (e.g. 1).
options OPTIONAL number The Options of the Transaction (e.g. 1).

🟢 200: OK

A bulk of Transactions were successfully sent.

{
  "data": {
    "numOfSentTxs": 2,
    "txsHashes": {
      "0": "6c41c71946b5b428c2cfb560e3ea425f8a00345de4bb2eb1b784387790914277",
      "1": "fa8195bae93d4609a6fc5972a7a6176feece39a6c4821acae2276701aee12fb0"
    }
  },
  "error": "",
  "code": "successful"
}

:::caution For Nodes (Observers or Validators with the HTTP API enabled), this endpoint only accepts transactions whose sender is in the Node's Shard. :::

Here's an example of a request:

POST https://gateway.multiversx.com/transaction/send-multiple HTTP/1.1
Content-Type: application/json

[
    {
        "nonce": 42,
        "value": "100000000000000000",
        "receiver": "erd1cux02zersde0l7hhklzhywcxk4u9n4py5tdxyx7vrvhnza2r4gmq4vw35r",
        "sender": "erd1njqj2zggfup4nl83x0nfgqjkjserm7mjyxdx5vzkm8k0gkh40ezqtfz9lg",
        "gasPrice": 1000000000,
        "gasLimit": 70000,
        "data": "Zm9vZCBmb3IgY2F0cw==", #base64 representation of "food for cats"
        "signature": "93207c579bf57be03add632b0e1624a73576eeda8a1687e0fa286f03eb1a17ffb125ccdb008a264c402f074a360442c7a034e237679322f62268b614e926d10f",
        "chainId": "1",
        "version": 1
}
    {
        "nonce": 43,
        "value": "100000000000000000",
        "receiver": "erd1cux02zersde0l7hhklzhywcxk4u9n4py5tdxyx7vrvhnza2r4gmq4vw35r",
        "sender": "erd1rhp4q3qlydyrrjt7dgpfzxk8n4f7yrat4wc6hmkmcnmj0vgc543s8h7hyl",
        "gasPrice": 1000000000,
        "gasLimit": 70000,
        "data": "YnVzIHRpY2tldHM=", #base64 representation of "bus tickets"
        "signature": "01535fd1d40d98b7178ccfd1729b3f526ee4542482eb9f591d83433f9df97ce7b91db07298b1d14308e020bba80dbe4bba8617a96dd7743f91ee4b03d7f43e00",
        "chainID": "1",
        "version": 1
    }
]

POST Simulate Transaction {#simulate-transaction}

Nodes and observers

https://gateway.multiversx.com/transaction/simulate

This endpoint allows one to send a signed Transaction to the Blockchain in order to simulate its execution. This can be useful in order to check if the transaction will be successfully executed before actually sending it. It receives the same request as the /transaction/send endpoint.

Move balance successful transaction simulation

<Tabs defaultValue="Request" values={[ {label: 'Request', value: 'Request'}, {label: 'Response', value: 'Response'}, ]}>

Body Parameters

Param Required Type Description
nonce REQUIRED number The Nonce of the Sender.
value REQUIRED string The Value to transfer, as a string representation of a Big Integer (can be "0").
receiver REQUIRED string The Address (bech32) of the Receiver.
sender REQUIRED string The Address (bech32) of the Sender.
senderUsername OPTIONAL string The base64 string representation of the Sender's username.
receiverUsername OPTIONAL string The base64 string representation of the Receiver's username.
gasPrice REQUIRED number The desired Gas Price (per Gas Unit).
gasLimit REQUIRED number The maximum amount of Gas Units to consume.
data OPTIONAL string The base64 string representation of the Transaction's message (data).
signature REQUIRED string The Signature (hex-encoded) of the Transaction.
chainID REQUIRED string The Chain identifier.
version REQUIRED number The Version of the Transaction (e.g. 1).
options OPTIONAL number The Options of the Transaction (e.g. 1).

A full response contains the fields above: SimulationResults

Field Type Description
status string success, fail ...
failReason string the error message
scResults []ApiSmartContractResult an array of smart contract results (if any)
receipts []ApiReceipt an array of the receipts (if any)
hash string the hash of the transaction

❕ Note that fields that are empty won't be included in the response. This can be seen in the examples below

🟢 200: OK

Transaction would be successful.

{
  "data": {
    "status": "success",
    "hash": "bb24ccaa2da8cddd6a3a8eb162e6ff62ad4f6e1914d9aa0cacde6772246ca2dd"
  },
  "error": "",
  "code": "successful"
}

🟢 200: Simulation was successful, but the transaction wouldn't be executed.

Invalid Transaction signature.

{
  "data": {
    "status": "fail",
    "failReason": "higher nonce in transaction",
    "hash": "bb24ccaa2da8cddd6a3a8eb162e6ff62ad4f6e1914d9aa0cacde6772246ca2dd"
  },
  "error": "",
  "code": "successful"
}

🔴 400: Bad request

{
  "data": null,
  "error": "transaction generation failed: invalid chain ID",
  "code": "bad_request"
}

Proxy

On the Proxy side, if the transaction to simulate is a cross-shard one, then the response format will contain two elements called senderShard and receiverShard which are of type SimulationResults explained above.

Example response for cross-shard transactions:

{
  "data": {
    "receiverShard": {
      "status": "success",
      "hash": "bb24ccaa2da8cddd6a3a8eb162e6ff62ad4f6e1914d9aa0cacde6772246ca2dd"
    },
    "senderShard": {
      "status": "success",
      "hash": "bb24ccaa2da8cddd6a3a8eb162e6ff62ad4f6e1914d9aa0cacde6772246ca2dd"
    }
  },
  "error": "",
  "code": "successful"
}

POST Estimate Cost of Transaction {#estimate-cost-of-transaction}

https://gateway.multiversx.com/transaction/cost

This endpoint is used to estimate the gas cost of a given transaction.

It performs a read-only simulation of the transaction against the current on-chain state, returning the number of gas units the transaction would consume if executed in that exact state.

How it works:

  • The endpoint takes all transaction input fields (value, sender, receiver, data, chainID, etc.).
  • It executes the transaction in a sandboxed, non-persistent environment, meaning it simulates execution without affecting the actual blockchain.
  • It uses the current state of the network (including smart contract storage, balances, etc.).
  • It returns the estimated gas (txGasUnits) and may also return smart contract results and events triggered by the simulation.

How does it apply to smart contracts?

For smart contracts, the endpoint simulates the contract call exactly as if it were executed live, including processing all logic, branches, and emitted events. The gas estimate reflects the computation and storage impact that would occur if the state remained unchanged at the time of actual execution.

How does it approximate the cost if the contract logic has variable gas usage?

If a smart contract’s logic has branches or conditional execution that result in variable gas usage (e.g., depending on internal storage state, previous executions, etc.), the estimation will only reflect the gas used by the path taken during this particular simulation.

Why is providing the correct nonce important?

Because the simulation engine mirrors real transaction behavior, it requires a valid and correct nonce to properly simulate the transaction. Using an outdated or incorrect nonce may lead to simulation failure.

Can the estimated gas differ from the actual cost?

Yes. Since the blockchain state may change between the moment you call /transaction/cost and when the transaction is actually sent to the network, the real gas usage can differ. This is especially true for smart contract calls that depend on dynamic or mutable state.

<Tabs defaultValue="Request" values={[ {label: 'Request', value: 'Request'}, {label: 'Response', value: 'Response'}, ]}>

Body Parameters

Param Required Type Description
value REQUIRED string The Value to transfer, as a string representation of a Big Integer (can be "0").
receiver REQUIRED string The Address (bech32) of the Receiver.
sender REQUIRED string The Address (bech32) of the Sender.
chainID REQUIRED string The Chain identifier.
version REQUIRED number The Version of the Transaction (e.g. 1).
nonce REQUIRED number The Sender nonce.
options OPTIONAL number The Options of the Transaction (e.g. 1).
data OPTIONAL string The base64 string representation of the Transaction's message (data).

🟢 200: OK

The cost is estimated successfully.

{
  "data": {
    "txGasUnits": "77000"
  },
  "error": "",
  "code": "successful"
}

:::tip

  • Use the returned txGasUnits value as the gasLimit in your actual transaction.
  • Make sure to provide the correct nonce of the transaction :::

:::tip Best practice: when sending the transaction, add ~10% extra gas to the estimated value to avoid underestimation and failure due to insufficient gas. :::

Here's an example of a request:

POST https://gateway.multiversx.com/transaction/cost HTTP/1.1
Content-Type: application/json

{
    "value": "100000",
    "receiver": "erd188nydpkagtpwvfklkl2tn0w6g40zdxkwfgwpjqc2a2m2n7ne9g8q2t22sr",
    "sender": "erd1l453hd0gt5gzdp7czpuall8ggt2dcv5zwmfdf3sd3lguxseux2fsmsgldz",
    "data": "dGhpcyBpcyBhbiBleGFtcGxl", #base64 representation of "this is an example"
    "chainID": "1",
    "version": 1,
    "nonce": 1
}

GET Get Transaction {#get-transaction}

https://gateway.multiversx.com/transaction/:txHash

This endpoint allows one to query the details of a Transaction.

<Tabs defaultValue="Request" values={[ {label: 'Request', value: 'Request'}, {label: 'Response', value: 'Response'}, ]}>

Path Parameters

Param Required Type Description
txHash REQUIRED string The hash (identifier) of the Transaction.

Query Parameters

Param Required Type Description
sender OPTIONAL string The Address of the sender - a hint to optimize the request.
withResults OPTIONAL bool Boolean parameter to specify if smart contract results and other details should be returned.

🟢 200: OK

Transaction details retrieved successfully.

{
  "data": {
    "transaction": {
      "type": "normal",
      "nonce": 3,
      "round": 186580,
      "epoch": 12,
      "value": "1000000000000000000",
      "receiver": "erd1...",
      "sender": "erd1...",
      "gasPrice": 1000000000,
      "gasLimit": 70000,
      "data": "Zm9yIHRlc3Rz",
      "signature": "1047...",
      "sourceShard": 2,
      "destinationShard": 1,
      "blockNonce": 186535,
      "miniblockHash": "e927...",
      "blockHash": "50a1...",
      "status": "executed"
    }
  },
  "error": "",
  "code": "successful"
}

Request URL:

https://gateway.multiversx.com/transaction/:txHash?withResults=true

Response:

The response can contain additional fields such as smartContractResults, or receipt

{
  "data": {
    "transaction": {
      "type": "normal",
      "nonce": 3,
      "round": 186580,
      "epoch": 12,
      "value": "1000000000000000000",
      "receiver": "erd1...",
      "sender": "erd1...",
      "gasPrice": 1000000000,
      "gasLimit": 70000,
      "data": "Zm9yIHRlc3Rz",
      "signature": "1047...",
      "sourceShard": 2,
      "destinationShard": 1,
      "blockNonce": 186535,
      "miniblockHash": "e927...",
      "blockHash": "50a1...",
      "status": "executed",
      "receipt": {
        "value": 100,
        "sender": "erd1...",
        "data": "...",
        "txHash": "b37..."
      },
      "smartContractResults": [
        {
          "hash": "...",
          "nonce": 5,
          "value": 1000,
          "receiver": "erd1...",
          "sender": "erd1...",
          "data": "@6f6b",
          "prevTxHash": "3638...",
          "originalTxHash": "3638...",
          "gasLimit": 0,
          "gasPrice": 1000000000,
          "callType": 0
        }
      ]
    }
  },
  "error": "",
  "code": "successful"
}

:::important The optional query parameter sender is only applicable to requests against the Proxy (not against the Observer Nodes). :::

GET Get Transaction Shallow Status {#get-transaction-status}

https://gateway.multiversx.com/transaction/:txHash/status

This endpoint allows one to query the shallow status of a transaction. For more details, see this.

<Tabs defaultValue="Request" values={[ {label: 'Request', value: 'Request'}, {label: 'Response', value: 'Response'}, ]}>

Path Parameters

Param Required Type Description
txHash REQUIRED string The hash (identifier) of the Transaction.

Query Parameters

Param Required Type Description
sender OPTIONAL string The Address of the sender - a hint to optimize the request.

🟢 200: OK

Transaction status retrieved successfully.

{
  "data": {
    "status": "success"
  },
  "error": "",
  "code": "successful"
}

:::important The optional query parameter sender is only applicable to requests against the Proxy (not against the Observer Nodes). :::

GET Get Transaction Process Status {#get-transaction-process-status}

https://gateway.multiversx.com/transaction/:txHash/process-status

This endpoint allows one to query the process status of a transaction. For more details, see this.

<Tabs defaultValue="Request" values={[ {label: 'Request', value: 'Request'}, {label: 'Response', value: 'Response'}, ]}>

Path Parameters

Param Required Type Description
txHash REQUIRED string The hash (identifier) of the Transaction.

🟢 200: OK

Transaction status retrieved successfully.

{
  "data": {
      "reason": ""
      "status": "success"
  },
  "error": "",
  "code": "successful"
}

GET Get Transactions Pool {#get-transactions-pool}

http://local-proxy-instance/transaction/pool

:::caution This endpoint isn't available on public gateway. However, it can be used on a local proxy instance, by setting AllowEntireTxPoolFetch to true :::

This endpoint allows one to fetch the entire transactions pool, merging the pools from each shard.

Default

<Tabs defaultValue="Request" values={[ {label: 'Request', value: 'Request'}, {label: 'Response', value: 'Response'}, ]}>

Example:

http://local-proxy-instance/transaction/pool

🟢 200: OK

Transaction status retrieved successfully.

{
  "data": {
    "txPool": {
      "regularTransactions": [
        {
          "txFields": {
            "hash": "84bb8a..."
          }
        },
        {
          "txFields": {
            "hash": "4e2c43..."
          }
        }
      ],
      "smartContractResults": [],
      "rewards": []
    },
    "error": "",
    "code": "successful"
}

Using custom fields

<Tabs defaultValue="Request" values={[ {label: 'Request', value: 'Request'}, {label: 'Response', value: 'Response'}, ]}>

Query Parameters

Param Required Type Description
fields OPTIONAL string A list of the fields to be included.
shard-id OPTIONAL string A specific shard id(0, 1, 2 etc. or 4294967295 for Metachain)

As seen above, if the fields item is empty, only the transaction hash will be displayed.

If the shard-id item is used, only the transactions from that specific shard's pool will be displayed.

Example request with shard id and fields:

https://gateway.multiversx.com/transaction/pool?shard-id=0&fields=sender,receiver,value

All possible values for fields item are:

  • hash
  • nonce
  • sender
  • receiver
  • gaslimit
  • gasprice
  • receiverusername
  • data
  • value

🟢 200: OK

Transaction status retrieved successfully.

{
  "data": {
    "txPool": {
      "regularTransactions": [
        {
          "txFields": {
            "gasLimit": 10,
            "gasPrice": 1000,
            "receiver": "erd1...",
            "sender": "erd1...",
            "value": "10000000000000000000"
          }
        }
      ],
      "smartContractResults": [
        {
          "txFields": {
            "gasLimit": 10,
            "gasPrice": 1000,
            "receiver": "erd1...",
            "sender": "erd1...",
            "value": "10000000000000000000"
          }
        }
      ],
      "rewards": [
        {
          "txFields": {
            "gasLimit": 10,
            "gasPrice": 1000,
            "receiver": "erd1...",
            "sender": "erd1...",
            "value": "10000000000000000000"
          }
        }
      ]
    }
  },
  "error": "",
  "code": "successful"
}

GET Get Transactions Pool for a Sender {#get-transactions-pool-for-a-sender}

https://gateway.multiversx.com/transaction/pool?by-sender=:sender:

This endpoint allows one to fetch all the transactions of a sender from the transactions pool.

Default

<Tabs defaultValue="Request" values={[ {label: 'Request', value: 'Request'}, {label: 'Response', value: 'Response'}, ]}>

Query Parameters

Param Required Type Description
by-sender REQUIRED string The Address of the sender.

Example:

https://gateway.multiversx.com/transaction/pool?by-sender=erd1qyu5wthldzr8wx5c9ucg8kjagg0jfs53s8nr3zpz3hypefsdd8ssycr6th

🟢 200: OK

Transaction status retrieved successfully.

{
  "data": {
    "txPool": {
      "transactions": [
        {
          "txFields": {
            "hash": "1daea5..."
          }
        }
      ]
    }
  },
  "error": "",
  "code": "successful"
}

Using custom fields

<Tabs defaultValue="Request" values={[ {label: 'Request', value: 'Request'}, {label: 'Response', value: 'Response'}, ]}>

Query Parameters

Param Required Type Description
by-sender REQUIRED string The Address of the sender.
fields OPTIONAL string A list of the fields to be included.

As seen above, if the fields item is empty, only the transaction hash will be displayed.

Example request with fields:

https://gateway.multiversx.com/transaction/pool?by-sender=erd1at9...&fields=sender,receiver,value

All possible values for fields item are:

  • hash
  • nonce
  • sender
  • receiver
  • gaslimit
  • gasprice
  • receiverusername
  • data
  • value

🟢 200: OK

Transaction status retrieved successfully.

{
  "data": {
    "txPool": {
      "transactions": [
        {
          "txFields": {
            "hash": "1daea...",
            "receiver": "erd1932...",
            "sender": "erd1at9ke...",
            "value": 0
          }
        }
      ]
    }
  },
  "error": "",
  "code": "successful"
}

GET Get the latest nonce of a sender from Tx Pool {#get-the-latest-nonce-of-a-sender-from-tx-pool}

https://gateway.multiversx.com/transaction/pool?by-sender=:sender:&last-nonce=true

This endpoint allows one to fetch the latest nonce of a sender from the transactions pool.

<Tabs defaultValue="Request" values={[ {label: 'Request', value: 'Request'}, {label: 'Response', value: 'Response'}, ]}>

Query Parameters

Param Required Type Description
by-sender REQUIRED string The Address of the sender.
last-nonce REQUIRED bool Specifies if the last nonce has to be returned.

🟢 200: OK

Transaction status retrieved successfully.

{
  "data": {
    "nonce": 38
  },
  "error": "",
  "code": "successful"
}

GET Get the nonce gaps of a sender from Tx Pool {#get-the-nonce-gaps-of-a-sender-from-tx-pool}

https://gateway.multiversx.com/transaction/pool?by-sender=:sender:&nonce-gaps=true

This endpoint allows one to fetch the nonce gaps of a sender from the transactions pool.

<Tabs defaultValue="Request" values={[ {label: 'Request', value: 'Request'}, {label: 'Response', value: 'Response'}, ]}>

Query Parameters

Param Required Type Description
by-sender REQUIRED string The Address of the sender.
nonce-gaps REQUIRED bool Specifies if the nonce gaps should be returned.

🟢 200: OK

Transaction status retrieved successfully.

{
  "data": {
    "nonceGaps": {
      "gaps": [
        {
          "from": 34,
          "to": 35
        },
        {
          "from": 37,
          "to": 37
        }
      ]
    }
  },
  "error": "",
  "code": "successful"
}