Getting started with Rosetta

The Rosetta API is made up of two core components; the Data API and the Construction API. Together, these APIs allow you to read and write to blockchains in a common format over a standard communication protocol. The specifications for these APIs can be found in the rosetta-specifications repository.

For full details, read the Rosetta API specification. For an overview of the interactions, view the Flow of Operations.

Here you will find developer examples, exchange examples, and the Rosetta API calls.

Developer Examples

This section outlines some examples that you can test out as a developer who wants to use Rosetta. However, we advise that you should exercise caution if testing these on mainnet.

Sample code for the typical Rosetta use cases:

Postman examples

This Postman Collection demonstrates how to query account balance, construct a multi-asset transaction, sign the transaction, and submit it. This scenario is tested nightly to ensure correctness. You simply import into Postman to get started.

Exchange Examples

This section provides some endpoint examples of how exchanges can use Rosetta for their integration needs:

  • Get address from public key
  • Determine transaction size
  • Get any information required to construct a transaction for a specific network
  • Create unsigned transaction
  • Confirm correctness of unsigned tx body
  • Create the signed transaction
  • Generate the transaction hash
  • Submit signed transaction to the blockchain

Get address from public key

/construction/derive

Request:

{
"network_identifier": {
"blockchain": "cardano",
"network": "testnet"
},
"public_key": {
"hex_bytes": "22ae46272bffe077cecc46e1494d790d4ad453ae1c4228aa0c2e9671dcb16341",
"curve_type": "edwards25519"
},
"metadata": {}
}

Response:

{
"address":
"addr_test1vzx9ztw59gzp7txrhs4z03u2sfzx8y49vxn3vchzasplx3cwph08p"
}

Determine transaction size

/construction/preprocess

Request:

{
"network_identifier": {
"blockchain": "cardano",
"network": "testnet"
},
"operations": [
{
"operation_identifier": {
"index": 0
},
"type": "input",
"status": "",
"account": {
"address": "addr_test1vzx9ztw59gzp7txrhs4z03u2sfzx8y49vxn3vchzasplx3cwph08p"
},
"amount": {
"value": "-999968487129",
"currency": {
"symbol": "ADA",
"decimals": 6
}
},
"coin_change": {
"coin_identifier": {
"identifier": "8f0e1bb31ff09a8dcc8a1b13d6ccb8f873f8d94b17bb7236c62e2d9d63d5426b:0"
},
"coin_action": "coin_spent"
},
"metadata": {
"tokenBundle": [
{
"policyId": "2bbd69730ab71f9c3825aef68d01400fc7c7f8270ed34082528b17a6",
"tokens": [
{
"value": "1",
"currency": {
"symbol": "31",
"decimals": 0,
"metadata": {
"policyId": "2bbd69730ab71f9c3825aef68d01400fc7c7f8270ed34082528b17a6"
}
}
},
{
"value": "1",
"currency": {
"symbol": "32",
"decimals": 0,
"metadata": {
"policyId": "2bbd69730ab71f9c3825aef68d01400fc7c7f8270ed34082528b17a6"
}
}
}
]
}
]
}
},
{
"operation_identifier": {
"index": 1
},
"type": "output",
"status": "",
"account": {
"address": "addr_test1vrpxrjmr5rk43ace43g2hnmxzguegns3vpqc8phx7tcu8wsgmynq6"
},
"amount": {
"value": "999968106116",
"currency": {
"symbol": "ADA",
"decimals": 6
}
},
"metadata": {
"tokenBundle": [
{
"policyId": "2bbd69730ab71f9c3825aef68d01400fc7c7f8270ed34082528b17a6",
"tokens": [
{
"value": "1",
"currency": {
"symbol": "31",
"decimals": 0,
"metadata": {
"policyId": "2bbd69730ab71f9c3825aef68d01400fc7c7f8270ed34082528b17a6"
}
}
},
{
"value": "1",
"currency": {
"symbol": "32",
"decimals": 0,
"metadata": {
"policyId": "2bbd69730ab71f9c3825aef68d01400fc7c7f8270ed34082528b17a6"
}
}
}
]
}
]
}
}
]
}
}

Response:

{
"options": {
"relative_ttl": 1000,
"transaction_size": 235
}
}

Get any information required to construct a transaction for a specific network

/construction/metadata

Request:

{
"network_identifier": {
"blockchain": "cardano",
"network": "testnet"
},
"options": {
"relative_ttl": 1000,
"transaction_size": 235
},
"public_keys": [
{
"hex_bytes": "22ae46272bffe077cecc46e1494d790d4ad453ae1c4228aa0c2e9671dcb16344",
"curve_type": "edwards25519"
}
]
}

Response:

{
"metadata": {
"ttl": "20416653"
},
"suggested_fee": [
{
"value": "165897",
"currency": {
"symbol": "ADA",
"decimals": 6
}
}
]
}

Create unsigned transaction

/construction/payloads

Request:

{
"network_identifier": {
"blockchain": "cardano",
"network": "testnet"
},
"operations": [
{
"operation_identifier": {
"index": 0
},
"type": "input",
"status": "",
"account": {
"address": "addr_test1vzx9ztw59gzp7txrhs4z03u2sfzx8y49vxn3vchzasplx3cwph08p"
},
"amount": {
"value": "-999968487129",
"currency": {
"symbol": "ADA",
"decimals": 6
}
},
"coin_change": {
"coin_identifier": {
"identifier": "8f0e1bb31ff09a8dcc8a1b13d6ccb8f873f8d94b17bb7236c62e2d9d63d5426b:0"
},
"coin_action": "coin_spent"
},
"metadata": {
"tokenBundle": [
{
"policyId": "2bbd69730ab71f9c3825aef68d01400fc7c7f8270ed34082528b17a6",
"tokens": [
{
"value": "1",
"currency": {
"symbol": "31",
"decimals": 0,
"metadata": {
"policyId": "2bbd69730ab71f9c3825aef68d01400fc7c7f8270ed34082528b17a6"
}
}
},
{
"value": "1",
"currency": {
"symbol": "32",
"decimals": 0,
"metadata": {
"policyId": "2bbd69730ab71f9c3825aef68d01400fc7c7f8270ed34082528b17a6"
}
}
}
]
}
]
}
},
{
"operation_identifier": {
"index": 1
},
"type": "output",
"status": "",
"account": {
"address": "addr_test1vrpxrjmr5rk43ace43g2hnmxzguegns3vpqc8phx7tcu8wsgmynq6"
},
"amount": {
"value": "999968106116",
"currency": {
"symbol": "ADA",
"decimals": 6
}
},
"metadata": {
"tokenBundle": [
{
"policyId": "2bbd69730ab71f9c3825aef68d01400fc7c7f8270ed34082528b17a6",
"tokens": [
{
"value": "1",
"currency": {
"symbol": "31",
"decimals": 0,
"metadata": {
"policyId": "2bbd69730ab71f9c3825aef68d01400fc7c7f8270ed34082528b17a6"
}
}
},
{
"value": "1",
"currency": {
"symbol": "32",
"decimals": 0,
"metadata": {
"policyId": "2bbd69730ab71f9c3825aef68d01400fc7c7f8270ed34082528b17a6"
}
}
}
]
}
]
}
}
],
"metadata": {
"ttl": "20416653"
},
"suggested_fee": [
{
"value": "165897",
"currency": {
"symbol": "ADA",
"decimals": 6
}
}
]
}

Response:

{
"unsigned_transaction": "8279010a613430303831383235383230386630653162623331666630396138646363386131623133643663636238663837336638643934623137626237323336633632653264396436336435343236623030303138313832353831643630633236316362363361306564353866373139616335306162636636363132333939343465313136303431383338366536663266316333626138323162303030303030653864326265363638346131353831633262626436393733306162373166396333383235616566363864303134303066633763376638323730656433343038323532386231376136613234313331303134313332303130323161303030356430353530333161303133373838386481a7746f7065726174696f6e5f6964656e746966696572a165696e64657800647479706565696e7075746673746174757360676163636f756e74a16761646472657373783f616464725f7465737431767a78397a74773539677a70377478726873347a3033753273667a783879343976786e337663687a6173706c78336377706830387066616d6f756e74a26576616c75656d2d3939393936383438373132396863757272656e6379a26673796d626f6c6341444168646563696d616c73066b636f696e5f6368616e6765a26f636f696e5f6964656e746966696572a16a6964656e7469666965727842386630653162623331666630396138646363386131623133643663636238663837336638643934623137626237323336633632653264396436336435343236623a306b636f696e5f616374696f6e6a636f696e5f7370656e74686d65746164617461a16b746f6b656e42756e646c6581a268706f6c69637949647838326262643639373330616237316639633338323561656636386430313430306663376337663832373065643334303832353238623137613666746f6b656e7382a26576616c756561316863757272656e6379a36673796d626f6c62333168646563696d616c7300686d65746164617461a168706f6c696379496478383262626436393733306162373166396333383235616566363864303134303066633763376638323730656433343038323532386231376136a26576616c756561316863757272656e6379a36673796d626f6c62333268646563696d616c7300686d65746164617461a168706f6c696379496478383262626436393733306162373166396333383235616566363864303134303066633763376638323730656433343038323532386231376136",
"payloads": [
{
"address": "addr_test1vzx9ztw59gzp7txrhs4z03u2sfzx8y49vxn3vchzasplx3cwph08p",
"hex_bytes": "6dd67acae1ad818eab971f27cc20bd6e030cf9783b32b0052d6d98bb13792b30",
"signature_type": "ed25519"
}
]
}

Confirm correctness of unsigned tx body

/construction/parse

Request:

{
"network_identifier": {
"blockchain": "cardano",
"network": "testnet"
},
"signed": false,
"transaction": "8279010a613430303831383235383230386630653162623331666630396138646363386131623133643663636238663837336638643934623137626237323336633632653264396436336435343236623030303138313832353831643630633236316362363361306564353866373139616335306162636636363132333939343465313136303431383338366536663266316333626138323162303030303030653864326265363638346131353831633262626436393733306162373166396333383235616566363864303134303066633763376638323730656433343038323532386231376136613234313331303134313332303130323161303030356430353530333161303133373838386481a7746f7065726174696f6e5f6964656e746966696572a165696e64657800647479706565696e7075746673746174757360676163636f756e74a16761646472657373783f616464725f7465737431767a78397a74773539677a70377478726873347a3033753273667a783879343976786e337663687a6173706c78336377706830387066616d6f756e74a26576616c75656d2d3939393936383438373132396863757272656e6379a26673796d626f6c6341444168646563696d616c73066b636f696e5f6368616e6765a26f636f696e5f6964656e746966696572a16a6964656e7469666965727842386630653162623331666630396138646363386131623133643663636238663837336638643934623137626237323336633632653264396436336435343236623a306b636f696e5f616374696f6e6a636f696e5f7370656e74686d65746164617461a16b746f6b656e42756e646c6581a268706f6c69637949647838326262643639373330616237316639633338323561656636386430313430306663376337663832373065643334303832353238623137613666746f6b656e7382a26576616c756561316863757272656e6379a36673796d626f6c62333168646563696d616c7300686d65746164617461a168706f6c696379496478383262626436393733306162373166396333383235616566363864303134303066633763376638323730656433343038323532386231376136a26576616c756561316863757272656e6379a36673796d626f6c62333268646563696d616c7300686d65746164617461a168706f6c696379496478383262626436393733306162373166396333383235616566363864303134303066633763376638323730656433343038323532386231376136"
}

Response:

(Response matches preprocess payload)

Locally sign payloads[0].hex_bytes from previous/payloads response to use in the next request.

Create the signed transaction

/construction/combine

Request:

{
"network_identifier": {
"blockchain": "cardano",
"network": testnet"
},
"unsigned_transaction": "8279010a613430303831383235383230386630653162623331666630396138646363386131623133643663636238663837336638643934623137626237323336633632653264396436336435343236623030303138313832353831643630633236316362363361306564353866373139616335306162636636363132333939343465313136303431383338366536663266316333626138323162303030303030653864326265363638346131353831633262626436393733306162373166396333383235616566363864303134303066633763376638323730656433343038323532386231376136613234313331303134313332303130323161303030356430353530333161303133373838386481a7746f7065726174696f6e5f6964656e746966696572a165696e64657800647479706565696e7075746673746174757360676163636f756e74a16761646472657373783f616464725f7465737431767a78397a74773539677a70377478726873347a3033753273667a783879343976786e337663687a6173706c78336377706830387066616d6f756e74a26576616c75656d2d3939393936383438373132396863757272656e6379a26673796d626f6c6341444168646563696d616c73066b636f696e5f6368616e6765a26f636f696e5f6964656e746966696572a16a6964656e7469666965727842386630653162623331666630396138646363386131623133643663636238663837336638643934623137626237323336633632653264396436336435343236623a306b636f696e5f616374696f6e6a636f696e5f7370656e74686d65746164617461a16b746f6b656e42756e646c6581a268706f6c69637949647838326262643639373330616237316639633338323561656636386430313430306663376337663832373065643334303832353238623137613666746f6b656e7382a26576616c756561316863757272656e6379a36673796d626f6c62333168646563696d616c7300686d65746164617461a168706f6c696379496478383262626436393733306162373166396333383235616566363864303134303066633763376638323730656433343038323532386231376136a26576616c756561316863757272656e6379a36673796d626f6c62333268646563696d616c7300686d65746164617461a168706f6c696379496478383262626436393733306162373166396333383235616566363864303134303066633763376638323730656433343038323532386231376136",
"signatures": [
{
"signing_payload": {
"account_identifier": {
"address": "addr_test1vzx9ztw59gzp7txrhs4z03u2sfzx8y49vxn3vchzasplx3cwph08p",
"metadata": {}
},
"hex_bytes": "6dd67acae1ad818eab971f27cc20bd6e030cf9783b32b0052d6d98bb13792b30",
"signature_type": "ed25519"
},
"public_key": {
"hex_bytes": "22ae46272bffe077cecc46e1494d790d4ad453ae1c4228aa0c2e9671dcb16341",
"curve_type": "edwards25519"
},
"signature_type": "ed25519",
"hex_bytes": "c7ba69cc50abce863c4900e55289ea27f473073b58fbd44a310140f3fb20494019f674588a2df9d8b6d454c55643a96e26dee332ef060e5960357f65687dde02"
}
]
}

Response:

{
"signed_transaction": "827901de3833613430303831383235383230386630653162623331666630396138646363386131623133643663636238663837336638643934623137626237323336633632653264396436336435343236623030303138313832353831643630633236316362363361306564353866373139616335306162636636363132333939343465313136303431383338366536663266316333626138323162303030303030653864326265363638346131353831633262626436393733306162373166396333383235616566363864303134303066633763376638323730656433343038323532386231376136613234313331303134313332303130323161303030356430353530333161303133373838386461313030383138323538323032326165343632373262666665303737636563633436653134393464373930643461643435336165316334323238616130633265393637316463623136333431353834306337626136396363353061626365383633633439303065353532383965613237663437333037336235386662643434613331303134306633666232303439343031396636373435383861326466396438623664343534633535363433613936653236646565333332656630363065353936303335376636353638376464653032663681a7746f7065726174696f6e5f6964656e746966696572a165696e64657800647479706565696e7075746673746174757360676163636f756e74a16761646472657373783f616464725f7465737431767a78397a74773539677a70377478726873347a3033753273667a783879343976786e337663687a6173706c78336377706830387066616d6f756e74a26576616c75656d2d3939393936383438373132396863757272656e6379a26673796d626f6c6341444168646563696d616c73066b636f696e5f6368616e6765a26f636f696e5f6964656e746966696572a16a6964656e7469666965727842386630653162623331666630396138646363386131623133643663636238663837336638643934623137626237323336633632653264396436336435343236623a306b636f696e5f616374696f6e6a636f696e5f7370656e74686d65746164617461a16b746f6b656e42756e646c6581a268706f6c69637949647838326262643639373330616237316639633338323561656636386430313430306663376337663832373065643334303832353238623137613666746f6b656e7382a26576616c756561316863757272656e6379a36673796d626f6c62333168646563696d616c7300686d65746164617461a168706f6c696379496478383262626436393733306162373166396333383235616566363864303134303066633763376638323730656433343038323532386231376136a26576616c756561316863757272656e6379a36673796d626f6c62333268646563696d616c7300686d65746164617461a168706f6c696379496478383262626436393733306162373166396333383235616566363864303134303066633763376638323730656433343038323532386231376136"
}

You can use /construction/parse again to confirm the correctness of signed transaction here if you change signed to true.

Generate the tx hash

/construction/hash

Request:

{
"network_identifier": {
"blockchain": "cardano",
"network": "testnet"
},
"signed_transaction": "827901de3833613430303831383235383230386630653162623331666630396138646363386131623133643663636238663837336638643934623137626237323336633632653264396436336435343236623030303138313832353831643630633236316362363361306564353866373139616335306162636636363132333939343465313136303431383338366536663266316333626138323162303030303030653864326265363638346131353831633262626436393733306162373166396333383235616566363864303134303066633763376638323730656433343038323532386231376136613234313331303134313332303130323161303030356430353530333161303133373838386461313030383138323538323032326165343632373262666665303737636563633436653134393464373930643461643435336165316334323238616130633265393637316463623136333431353834306337626136396363353061626365383633633439303065353532383965613237663437333037336235386662643434613331303134306633666232303439343031396636373435383861326466396438623664343534633535363433613936653236646565333332656630363065353936303335376636353638376464653032663681a7746f7065726174696f6e5f6964656e746966696572a165696e64657800647479706565696e7075746673746174757360676163636f756e74a16761646472657373783f616464725f7465737431767a78397a74773539677a70377478726873347a3033753273667a783879343976786e337663687a6173706c78336377706830387066616d6f756e74a26576616c75656d2d3939393936383438373132396863757272656e6379a26673796d626f6c6341444168646563696d616c73066b636f696e5f6368616e6765a26f636f696e5f6964656e746966696572a16a6964656e7469666965727842386630653162623331666630396138646363386131623133643663636238663837336638643934623137626237323336633632653264396436336435343236623a306b636f696e5f616374696f6e6a636f696e5f7370656e74686d65746164617461a16b746f6b656e42756e646c6581a268706f6c69637949647838326262643639373330616237316639633338323561656636386430313430306663376337663832373065643334303832353238623137613666746f6b656e7382a26576616c756561316863757272656e6379a36673796d626f6c62333168646563696d616c7300686d65746164617461a168706f6c696379496478383262626436393733306162373166396333383235616566363864303134303066633763376638323730656433343038323532386231376136a26576616c756561316863757272656e6379a36673796d626f6c62333268646563696d616c7300686d65746164617461a168706f6c696379496478383262626436393733306162373166396333383235616566363864303134303066633763376638323730656433343038323532386231376136"
}

Response

{
"transaction_identifier": {
"hash": "6dd67acae1ad818eab971f27cc20bd6e030cf9783b32b0052d6d98bb13792b30"
}
}

Submit signed transaction to the blockchain

/construction/submit

Request:

{
"network_identifier": {
"blockchain": "cardano",
"network": "testnet"
},
"signed_transaction": "827901de3833613430303831383235383230386630653162623331666630396138646363386131623133643663636238663837336638643934623137626237323336633632653264396436336435343236623030303138313832353831643630633236316362363361306564353866373139616335306162636636363132333939343465313136303431383338366536663266316333626138323162303030303030653864326265363638346131353831633262626436393733306162373166396333383235616566363864303134303066633763376638323730656433343038323532386231376136613234313331303134313332303130323161303030356430353530333161303133373838386461313030383138323538323032326165343632373262666665303737636563633436653134393464373930643461643435336165316334323238616130633265393637316463623136333431353834306337626136396363353061626365383633633439303065353532383965613237663437333037336235386662643434613331303134306633666232303439343031396636373435383861326466396438623664343534633535363433613936653236646565333332656630363065353936303335376636353638376464653032663681a7746f7065726174696f6e5f6964656e746966696572a165696e64657800647479706565696e7075746673746174757360676163636f756e74a16761646472657373783f616464725f7465737431767a78397a74773539677a70377478726873347a3033753273667a783879343976786e337663687a6173706c78336377706830387066616d6f756e74a26576616c75656d2d3939393936383438373132396863757272656e6379a26673796d626f6c6341444168646563696d616c73066b636f696e5f6368616e6765a26f636f696e5f6964656e746966696572a16a6964656e7469666965727842386630653162623331666630396138646363386131623133643663636238663837336638643934623137626237323336633632653264396436336435343236623a306b636f696e5f616374696f6e6a636f696e5f7370656e74686d65746164617461a16b746f6b656e42756e646c6581a268706f6c69637949647838326262643639373330616237316639633338323561656636386430313430306663376337663832373065643334303832353238623137613666746f6b656e7382a26576616c756561316863757272656e6379a36673796d626f6c62333168646563696d616c7300686d65746164617461a168706f6c696379496478383262626436393733306162373166396333383235616566363864303134303066633763376638323730656433343038323532386231376136a26576616c756561316863757272656e6379a36673796d626f6c62333268646563696d616c7300686d65746164617461a168706f6c696379496478383262626436393733306162373166396333383235616566363864303134303066633763376638323730656433343038323532386231376136"
}

API Calls

This section outlines the available Rosetta API calls:

Get brief information about transactions

$ curl -X POST '$BASEURL/block' \
-H "Content-Type: application/json" \
-d '{ "network_identifier": {"blockchain": "cardano", "network": "mainnet" }, "metadata": {}, "block_identifier": {"index": "5264122" }}'

Get block’s summary information

$ curl -X POST '$BASEURL/block' \
-H "Content-Type: application/json" \
-d '{ "network_identifier": {"blockchain": "cardano", "network": "mainnet" }, "metadata": {}, "block_identifier": {"index": "5264122" }}'

Get information about the N latest transactions

# Get the current block identifier
$ curl -X POST '$BASEURL/network/status' \
-H "Content-Type: application/json" \
-d '{ "network_identifier": { "blockchain": "cardano", "network": "mainnet" }, "metadata": {} }' | jq .current_block_identifier.index
5264122
# Fetch information from it
$ curl -X POST '$BASEURL/block' \
-H "Content-Type: application/json" \
-d '{ "network_identifier": {"blockchain": "cardano", "network": "mainnet" }, "metadata": {}, "block_identifier": {"index": "5264122" }}'

Get summary information about a transaction

$ curl $BASEURL/api/txs/summary/382a5274ebf102910c6c923a8b11f108e79ecedb5d7433cd0dd15a8a443f0fa5
Get summary information about an address
$ curl -X POST '$BASEURL/account/balance' \
-H "Content-Type: application/json" \
-d '{ "network_identifier": { "blockchain": "cardano", "network": "mainnet" }, "metadata": {}, "account_identifier": { "address": "DdzFFzCqrhsqKd92VGNM9Ts1Ms62J2FaSRmf8t1bQa1VugDmcUJzeU8TRFnGDDUR6f1m9VaJJG1GfnzxVjKGBbBAVGT9sPBseREYzP3E" }, "metadata": {}}'

Get address information specific to a block

$ curl -X POST '$BASEURL/account/balance' \
-H "Content-Type: application/json" \
-d '{ "network_identifier": { "blockchain": "cardano", "network": "mainnet" }, "metadata": {}, "account_identifier": { "address": "DdzFFzCqrhsqKd92VGNM9Ts1Ms62J2FaSRmf8t1bQa1VugDmcUJzeU8TRFnGDDUR6f1m9VaJJG1GfnzxVjKGBbBAVGT9sPBseREYzP3E" }, "metadata": {}, "block_identifier": {"index": "5264122","hash": "b5426334221805b3c161ec07b02722728ced7b5c38a9cc60962e819620ecbf9a" },"currencies": {"symbol": "ada", "decimals": 8 }}'

© IOHK 2015 - 2022


Cardano Logo

Cardano is an open-source project.

Cardano is a software platform ONLY and does not conduct any independent diligence on, or substantive review of, any blockchain asset, digital currency, cryptocurrency or associated funds. You are fully and solely responsible for evaluating your investments, for determining whether you will exchange blockchain assets based on your own judgement, and for all your decisions as to whether to exchange blockchain assets with Cardano. In many cases, blockchain assets you exchange on the basis of your research may not increase in value, and may decrease in value. Similarly, blockchain assets you exchange on the basis of your research may fall or rise in value after your exchange.

Past performance is not indicative of future results. Any investment in blockchain assets involves the risk of loss of part or all of your investment. The value of the blockchain assets you exchange is subject to market and other investment risks