# Chains and tokens

Read network configuration before constructing a trade, withdrawal, or settlement claim. Chain keys, token addresses, and decimal counts come from the API.

## Discover networks

~~~bash GET /v1/chains
curl https://starswap.cc/api/v1/chains \
  -H "Authorization: Bearer $STARSWAP_API_KEY"
~~~

Each item includes `key`, `name`, `chainId`, `family`, `nativeCurrency`, `token`, `vault`, and `tradingEnabled`. Use `key` in requests and `family` to choose an address from the wallet's `addresses` array. The `token` object describes the chain's settlement asset. Do not confuse its decimals with `nativeCurrency.decimals`.

The configured networks include BNB Smart Chain, Base, Robinhood Chain, and Solana. Check the returned descriptors for current availability and settlement assets. `tradingEnabled` controls whether a network accepts trades.

## Amount units

| Field | Unit | Example |
| --- | --- | --- |
| `amountMicros`, `availableMicros`, `vaultFeeMicros` | One millionth of a settlement token | `"25000000"` means 25 tokens |
| Buy `amountRaw` | Input settlement token's native units | At 18 decimals, 25 tokens is `"25000000000000000000"` |
| Sell or direct-withdrawal `amountRaw` | Selected asset's native units | At 9 decimals, `"1000000000"` means one token |
| `slippagePercentage` | Decimal percentage text | `"1"` means one percent |

Settlement assets use either 6 or 18 decimals. At 18 decimals, multiply a micro-unit amount by `10^12` to obtain raw units. Settlement operations reject amounts below a whole micro-unit. Keep integer amounts as strings at the JSON boundary and use exact integer arithmetic internally. Never round financial amounts through JavaScript `Number`.

## Find a token on one network

`GET /v1/tokens` requires `chain` and `query`. Search by name, symbol, contract address, or a qualified native alias.

~~~bash GET /v1/tokens
curl 'https://starswap.cc/api/v1/tokens?chain=base&query=base%3Anative' \
  -H "Authorization: Bearer $STARSWAP_API_KEY"
~~~

Every trading-enabled chain accepts the exact `<chain-key>:native` alias. A qualified alias searches only that chain. The returned canonical native address is `solana:native` for SOL or `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` for EVM gas tokens. Use the canonical address in subsequent requests. Preserve Solana address casing.

## Resolve a complete address

`GET /v1/tokens/resolve?query=ADDRESS` resolves a complete address across compatible networks. Add `chain` to constrain the lookup. The response includes a `status` of `unique`, `ambiguous`, or `not_found` and chain-qualified `items`.

Select automatically only after `unique`. Ask the trader to choose a network for `ambiguous`. A transient or partial provider failure must not be treated as proof that an address exists on only one chain. Cached token identity can help navigation, but fetch a current token snapshot and a fresh quote before execution.