# Getting Started

This guide takes an integration from credentials to a reconciled order. It uses
REST for the first write; latency-sensitive strategies should move the same
order model to the [write WebSocket](/api/exchange-websocket) after validating
the lifecycle.

## 1. Set your credentials

Beta onboarding gives you an approved EVM wallet. That wallet address is your
public Mosaiq `user`.

Create an API key from an authenticated Para wallet session:

```bash
curl https://production.mosaiq.0d.finance/v1/apiKey \
  -H "Authorization: Bearer $PARA_JWT" \
  -H "Content-Type: application/json" \
  -d '{}'
```

If the Para session contains multiple EVM wallets, also send
`X-Tessera-Wallet: <approved-wallet>`. The response returns the raw key once.
Creating a key revokes the previous key; keys expire after 30 days.

Set the values used below:

```bash
export MOSAIQ_API_BASE_URL=https://production.mosaiq.0d.finance
export MOSAIQ_USER=0x0000000000000000000000000000000000000001
export MOSAIQ_API_KEY=<your-api-key>
```

Trading requests authenticate with the API key:

```http
Authorization: Bearer <your-api-key>
```

## 2. Inspect the account and market catalog

Fetch the current account snapshot before sending an order:

```bash
curl "$MOSAIQ_API_BASE_URL/v1/clearinghouseState?user=$MOSAIQ_USER"
```

Use the response to check:

* `clearinghouseState.marginSummary.availableFunds` for opening capacity;
* `clearinghouseState.userCaps` for account-level limits;
* `clearinghouseState.meta.venues` for venue reachability;
* `clearinghouseState.universe[*].venues[*]` for active venue codes, trading
  status, tick size, size increment, and minimum notional.

Use the canonical asset in `clearinghouseState.universe[*].name` as the order
field `a`. Use the selected `venues[*].venue` exactly as returned. Do not
derive venue symbols or precision rules in the client.

## 3. Start lifecycle subscriptions

Open the read WebSocket before the first write and subscribe to both order
state and fills:

```ts
const apiBaseUrl = 'https://production.mosaiq.0d.finance'
const user = '0x0000000000000000000000000000000000000001'

const url = new URL('/v1/ws', apiBaseUrl)
url.protocol = 'wss:'
url.searchParams.set('user', user)

const ws = new WebSocket(url)

ws.addEventListener('open', () => {
  for (const type of ['orderUpdates', 'userFills']) {
    ws.send(JSON.stringify({ method: 'subscribe', subscription: { type } }))
  }
})

ws.addEventListener('message', (event) => {
  const message = JSON.parse(event.data)
  if (message.status !== 'ok') return

  if (message.topic === 'orderUpdates') {
    for (const order of message.data.orderUpdates) {
      console.log('order', order.cloid, order.status)
    }
  }

  if (message.topic === 'userFills') {
    for (const fill of message.data.userFills) {
      console.log('fill', fill.cloid, fill.fillId)
    }
  }
})
```

The first message for each topic is a snapshot. Store order transitions by
`cloid` and fills by `fillId`; processing must be idempotent.

## 4. Fund the account

Create a tracked deposit request:

```bash
curl "$MOSAIQ_API_BASE_URL/v1/exchange" \
  -H "Authorization: Bearer $MOSAIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"deposit","amount":"100"}'
```

Send the exact USDC amount on Arbitrum, from the registered wallet, to the
returned `to` address before `expiresAtMs`. Mosaiq credits the account only
after observing a matching transfer. Check the resulting balance through
`clearinghouseState`; Para-authenticated clients can inspect request status
through [`GET /v1/funding`](/api/funding).

## 5. Submit an order

Choose an active market and values that satisfy the selected venue's live
constraints. Give every placement a fresh, non-zero 128-bit hexadecimal
`cloid`.

The following request places one post-only limit order. Set the variables from
your strategy's current market data before running it:

```bash
export MOSAIQ_ASSET=BTC
export MOSAIQ_VENUE=hyperliquid
export MOSAIQ_LIMIT_PRICE=<current-post-only-price>
export MOSAIQ_SIZE=<valid-base-size>
export MOSAIQ_CLOID=0x00000000000000000000000000000001

curl "$MOSAIQ_API_BASE_URL/v1/exchange" \
  -H "Authorization: Bearer $MOSAIQ_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<JSON
{
  "type": "place",
  "orders": [
    {
      "a": "$MOSAIQ_ASSET",
      "b": "buy",
      "p": "$MOSAIQ_LIMIT_PRICE",
      "s": "$MOSAIQ_SIZE",
      "venue": "$MOSAIQ_VENUE",
      "t": "Alo",
      "c": "$MOSAIQ_CLOID"
    }
  ]
}
JSON
```

The response contains one result in `data[0]`:

```jsonc
{
  "status": "ok",
  "data": [
    {
      "status": "accepted",
      "orderId": "...",
      "cloid": "0x00000000000000000000000000000001",
      "venue": "hyperliquid"
    }
  ],
  "server_time_ms": 1780000000100,
  "server_receive_time_ms": 1780000000088
}
```

`accepted` is not fill finality. Continue tracking the `cloid` on
`orderUpdates`. Treat `userFills` as execution truth and a later
`clearinghouseState` snapshot as account truth.

## 6. Cancel or reconcile

Cancel the resting order by `cloid` and venue:

```bash
curl "$MOSAIQ_API_BASE_URL/v1/exchange" \
  -H "Authorization: Bearer $MOSAIQ_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<JSON
{
  "type": "cancel",
  "orders": [
    { "venue": "$MOSAIQ_VENUE", "c": "$MOSAIQ_CLOID" }
  ]
}
JSON
```

If a request or connection ends without a definitive response, do not blindly
resend it. Reconnect, consume fresh lifecycle snapshots, and query
[`GET /v1/openOrders?cloid=<cloid>`](/api/open-orders) before deciding whether
to retry.

For a production integration, continue with:

* [Write WebSocket](/api/exchange-websocket) for authenticated, pipelined
  order entry;
* [Optimizing latency](/api/optimizing-latency) for socket management,
  ordering, and recovery;
* [Exchange API](/api/exchange) for modify, mass cancel, market orders,
  batching, validation, and error semantics.