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:
- Sending transactions
- Staking key registration and delegation
- Withdrawals
- Sending transactions with single multi assets
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 }}'