> ## Documentation Index
> Fetch the complete documentation index at: https://docs.outcome.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# HIP-4 Coin Names, Asset IDs, and Side Conventions

> The two coin formats used in HIP-4, how asset IDs are computed, the coin helper functions and sideIndex conventions.

HIP-4 uses two distinct coin name formats to represent prediction market instruments. One format names an outcome as a whole. The other identifies a specific tradeable side within that outcome and is what you use when placing orders, reading order books and prices, or querying fills. Understanding which format to use - and how the SDK's helper functions convert between them - is essential for working with market data and the trading API.

## The two coin formats

| Format | Example | Use case |
| - | - | - |
| `@{outcomeId}` | `@516` | Outcome-level name (`outcomeCoin()`); not used for prices or orders |
| `#{outcomeId}{sideIndex}` | `#5160`, `#5161` | Tradeable side instrument (order books, prices, trading, fills) |

### Outcome coin (`@{outcomeId}`)

The `@`-prefixed coin names an outcome as a whole. The SDK builds it with `outcomeCoin()` and parses it with `parseOutcomeCoin()`. You do **not** use it for order placement or price lookups: `allMids` keys HIP-4 prices by side coin (`#5160`), and an `@` key in `allMids` (such as `@107`) is a regular spot pair.

```typescript theme={null}
outcomeCoin(516); // "@516"
```

### Side coin (`#{outcomeId}{sideIndex}`)

The `#`-prefixed coin is the tradeable instrument for a specific side of an outcome. You pass it to order placement and order book queries, and it keys prices in `allMids` and appears in fill records. The outcome ID and side index are concatenated with no separator: `#5160` means outcome 516, side 0.

Spot balances use a third prefix. Hyperliquid's `spotClearinghouseState` reports an outcome side balance as `+5160`, so position `outcome` values use that form. `parseSideCoin()` accepts both `#` and `+`.

```typescript theme={null}
// Place an order on the "Yes" side of outcome 516
await hip4.trading.placeOrder({
  marketId: "516",
  outcome: "#5160", // side coin - outcome 516, side 0
  side: "buy",
  type: "limit",
  price: "0.65",
  amount: "100",
});
```

<Note>
  The `marketId` field is always the outcome ID as a plain string - for example,
  `"516"`. It is not a coin string. The `outcome` field is the side coin like
  `"#5160"`.
</Note>

## Asset IDs

Hyperliquid's order wire format uses numeric asset IDs, not coin strings. The SDK computes these for you, but it's useful to understand the formulas.

**HIP-4 outcome sides:**

```
assetId = 100_000_000 + outcomeId * 10 + sideIndex
```

For example, outcome 516, side 0:

```
100_000_000 + 516 * 10 + 0 = 100_005_160
```

**Spot pairs** (for example USDH/USDC or HYPE/USDC):

```
assetId = 10_000 + spotPairIndex
```

The two ranges don't overlap, so the asset ID tells you which kind of market an order targets.

## Coin helper functions

Import the coin helpers from `@outcome.xyz/hip4`:

```typescript theme={null}
import {
  sideCoin,
  sideAssetId,
  parseSideCoin,
  outcomeCoin,
} from "@outcome.xyz/hip4";
```

### `sideCoin(outcomeId, sideIndex)`

Builds a side coin string from an outcome ID and side index.

```typescript theme={null}
sideCoin(516, 0); // "#5160"
sideCoin(516, 1); // "#5161"
sideCoin(9, 0); // "#90"
```

### `sideAssetId(outcomeId, sideIndex)`

Computes the numeric asset ID for use in order wire format.

```typescript theme={null}
sideAssetId(516, 0); // 100005160
sideAssetId(516, 1); // 100005161
sideAssetId(9, 0); // 100000090
```

### `parseSideCoin(coin)`

Parses a side coin string back into its component parts.

```typescript theme={null}
parseSideCoin("#5160"); // { outcomeId: 516, sideIndex: 0 }
parseSideCoin("#5161"); // { outcomeId: 516, sideIndex: 1 }
parseSideCoin("#90"); // { outcomeId: 9, sideIndex: 0 }
```

### `outcomeCoin(outcomeId)`

Builds the outcome-level coin string. Use side coins, not this value, for prices and orders.

```typescript theme={null}
outcomeCoin(516); // "@516"
outcomeCoin(1338); // "@1338"
```

## Side index conventions

`sideIndex` is always 0 or 1. By convention:

* **Side 0** is the first side - typically "Yes", or the first named alternative (e.g. "Hypurr")
* **Side 1** is the second side - typically "No", or the second named alternative (e.g. "Usain Bolt")

The actual side names come from `sideSpecs` in the outcome metadata and are resolved by the SDK automatically. You can read them from the typed market object:

```typescript theme={null}
const market = markets[0] as DefaultBinaryMarket;

market.sides[0].name; // "Yes"   (sideIndex 0)
market.sides[0].coin; // "#5160"
market.sides[1].name; // "No"    (sideIndex 1)
market.sides[1].coin; // "#5161"
```

For labelled binary markets, the names can be anything:

```typescript theme={null}
market.sides[0].name; // "Hypurr"
market.sides[1].name; // "Usain Bolt"
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.