Transactions

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

POST Send Transaction

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

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

Request

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).

Response

🟢 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

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

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

Request

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).

Response

🟢 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

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

Request

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).

Response

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

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

This endpoint allows one to estimate the cost of a transaction.

Request

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.
data	OPTIONAL	string	The base64 string representation of the Transaction's message (data).
chainID	REQUIRED	string	The Chain identifier.
version	REQUIRED	number	The Version of the Transaction (e.g. 1).
nonce	OPTIONAL	number	The Sender nonce.

Response

🟢 200: OK

The cost is estimated successfully.

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

tip

This endpoint returns the cost on the transaction in gas units. The returned value can be used to fill in gasLimit field of the transaction.

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

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

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

Request

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.

Response

🟢 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"
}

info

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

GET Get Transaction Status

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

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

Request

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.

Response

🟢 200: OK

Transaction status retrieved successfully.

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

info

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

GET 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

Request

Example:

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

Response

🟢 200: OK

Transaction status retrieved successfully.

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

Using custom fields

Request

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

Response

🟢 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

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

Request

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

Response

🟢 200: OK

Transaction status retrieved successfully.

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

Using custom fields

Request

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

Response

🟢 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

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.

Request

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.

Response

🟢 200: OK

Transaction status retrieved successfully.

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

GET 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.

Request

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.

Response

🟢 200: OK

Transaction status retrieved successfully.

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