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 and the wallet provider contract as the next integration checkpoints.