Skip to main content

Native Tokens

Overview​

Native tokens on Cardano allow users to create and transact with custom tokens alongside ADA. In the Rosetta API implementation, these tokens are represented in both transaction operations and account balances.

info

More information about Native Tokens can be found in the Cardano Documentation.

Key Concepts​

  • symbol - The Asset Name stored in the Ledger (passed as ASCII string, changed in v1.3.2 released on 2025-09-05)
  • policyId - The Policy ID that controls the asset (passed as hex string)
  • Both values are required for token operations
note

Token Name is not required by Cardano protocol rules. Since Mesh symbol is a required field, it should be represented as an empty string "" when no name is provided.

Operations with Native Tokens​

Native tokens can be included in both input and output operations. The token bundles are associated with each operation as metadata.

Sign Convention

When spending native tokens in input operations, the token values in the tokenBundle MUST be negative. This follows the same convention as ADA amounts in inputs. Output operations use positive values.

Minting and Burning Observations

Rosetta API only supports transferring existing native tokens through the Construction API. Minting and burning operations cannot be initiated through Rosetta.

However, when querying blockchain data through endpoints like /block/transactions, you may observe minting and burning transactions with these patterns:

  • Minting: Token appears only in outputs with positive value (no corresponding input)
  • Burning: Token appears only in inputs with negative value (no corresponding output)
  • Partial burning: Token in inputs (negative) and outputs (positive remainder). The burned amount is the difference
  • Transfer: Token in both inputs (negative) and outputs (positive) with net zero change

The Rosetta representation doesn't explicitly label these as mint/burn operations - this must be inferred from the token flow patterns.

{
  "operation_identifier": { "index": 0 },
  "type": "input",
  "account": {
    "address": "addr1vxa5pudxg77g3sdaddecmw8tvc6hmynywn49lltt4fmvn7cpnkcpx"
  },
  "amount": {
    "value": "-90000",
    "currency": { "symbol": "ADA", "decimals": 6 }
  },
  "coin_change": {
    "coin_identifier": {
      "identifier": "2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f:1"
    },
    "coin_action": "coin_spent"
  },
  "metadata": {
    "tokenBundle": [
      {
        "policyId": "b0d07d45fe9514f80213f4020e5a61241458be626841cde717cb38a7",
        "tokens": [
          {
            "value": "-10000",
            "currency": { "symbol": "nutcoin", "decimals": 0 }
          }
        ]
      }
    ]
  }
}

Account Balance and UTXO Queries​

Cardano Rosetta provides two separate endpoints for querying account information:

Account Balance​

The /account/balance endpoint returns the aggregated balance of all ADA and native tokens owned by an address.

Note on Stake Addresses

When queried with a stake address (reward address), the response includes available rewards that can be withdrawn.

Known Issue: Historical queries for stake address rewards currently return the current reward value instead of the historical value at the specified block. See Issue #590.

Request:

{
  "network_identifier": {"blockchain": "cardano", "network": "mainnet"},
  "account_identifier": {"address": "addr1..."}
}

Response:

{
  "block_identifier": {
    "index": 10453789,
    "hash": "6e9e89632bc5c72030d3a486647e889c48d63e4da0643191b13566ad816d2d57"
  },
  "balances": [
    {
      "value": "71103107",
      "currency": {
        "symbol": "ADA",
        "decimals": 6
      }
    },
    {
      "value": "10000",
      "currency": {
        "symbol": "nutcoin",
        "decimals": 0,
        "metadata": {
          "policyId": "b0d07d45fe9514f80213f4020e5a61241458be626841cde717cb38a7"
        }
      }
    }
  ]
}