# Integration principles

> Handle IceRoot identities, amounts, network state, and errors consistently.

Source: https://docs.iceroot.com/developers/integration-principles/

Reliable integrations keep identity, precision, and state explicit.

## Keep asset identity intact

Use the Asset ID as a key. Store names, symbols, and logos as metadata. A ticker is a display value, and two records with the same ticker may describe different assets.

## Preserve exact amounts

Keep API decimal strings or convert them to integer base units using the asset’s precision. Use exact arithmetic for totals, balance checks, and fees.

Do not use `Number` for amounts that require more precision than JavaScript floating point can preserve. Format a value for display only after its arithmetic is complete.

## Track states separately

| State     | What it establishes                          |
| --------- | -------------------------------------------- |
| Prepared  | An application assembled an action           |
| Signed    | The relevant identity authorized exact bytes |
| Submitted | A service received the action                |
| Included  | A recorded block contains it                 |
| Final     | The network’s finality rule is satisfied     |

Only show a state when its data source supports it. A timestamp from your server is not a block timestamp. A local simulation is not a chain confirmation.

## Fail visibly

Distinguish an empty result from a failed request. Keep stale data labeled when retrying, and avoid silently substituting local examples.

For write operations, follow the selected API’s transaction identity and retry rules. A timeout alone does not establish whether a submitted action was accepted.

## Separate identity from permission

A valid signature proves control of a key for a particular message. Your server still has to verify the requested purpose, network, expiry, ownership, and permissions.

Use [network configuration](https://docs.iceroot.com/core/network-configuration/index.md) and the [wallet provider contract](https://docs.iceroot.com/developers/wallet-provider/index.md) as the next integration checkpoints.
