# Quickstart

> Your first call in under two minutes, in the free sandbox. Then connect your broker account and run the same calls.

Source: https://tickwire.io/docs/quickstart/

Start in the [sandbox](https://tickwire.io/docs/sandbox/): no card, no broker login, no terminal to wait for. When
your code works there, connect a broker account and change only the key and the account id. Demo,
small funded or live: it's your choice. The examples use `curl`.

```bash
export TW=https://api.tickwire.io
```

## 1. Get a sandbox key and account

```bash
curl -s -X POST "$TW/v1/sandbox/signup" -H "content-type: application/json" -d '{"platform": "mt5"}'
```

```json
{
  "sandbox": true,
  "apiKey": "twsk_4b1e…",
  "account": { "id": "acc_7Qx", "server": "Tickwire-Sandbox", "login": "1000",
               "state": "DEPLOYED", "connectionStatus": "CONNECTED" }
}
```

The key is shown once. Set it, then follow steps 2 to 6 below with `acc_7Qx`:

```bash
export TW_KEY=twsk_4b1e…
```

Sandbox answers carry `X-Tickwire-Sandbox: true`. Want to see an order that can't be confirmed, a rejection
or a disconnect? Create accounts with the [magic logins](https://tickwire.io/docs/sandbox/#magic-logins).

### Or connect a broker account

You need a live Tickwire API key and a broker account (login, password and server name, e.g.
`YourBroker-Server`):

```bash
export TW_KEY=your-live-api-key
```

```bash
curl -s -X POST "$TW/users/current/accounts" \
  -H "auth-token: $TW_KEY" \
  -H "transaction-id: $(openssl rand -hex 16)" \
  -H "content-type: application/json" \
  -d '{
    "name": "my account",
    "platform": "mt5",
    "server": "YourBroker-Server",
    "login": "12345678",
    "password": "your-password",
    "magic": 1000
  }'
```

If broker detection is still running you get **202** with a `Retry-After` header. Send the same
request again, with the **same** `transaction-id`, after that many seconds. You end with **201** and
the account id:

```json
{ "id": "acc_7Qx", "state": "DEPLOYING" }
```

If the server name is unknown you get `E_SRV_NOT_FOUND` with suggested names. See
[broker onboarding](https://tickwire.io/docs/broker-onboarding/).

The password is write-only. We never return it or write it to logs.

## 2. Wait for the account to connect

```bash
curl -s "$TW/users/current/accounts/acc_7Qx" -H "auth-token: $TW_KEY"
```

Wait for `"connectionStatus": "CONNECTED"` and `"health": {"status": "healthy", …}`. That means
the broker link is up, the account was read, and ticks are moving. Usually this takes under a
minute; a sandbox account is ready at once. `stale` means connected but quotes frozen (often a
closed market). See [Health](https://tickwire.io/docs/health/).

## 3. Read the account

```bash
curl -s "$TW/users/current/accounts/acc_7Qx/account-information" -H "auth-token: $TW_KEY"
```

```json
{
  "platform": "mt5",
  "broker": "Your Broker Ltd",
  "currency": "USD",
  "balance": 10000,
  "equity": 10000,
  "margin": 0,
  "freeMargin": 10000,
  "leverage": 500,
  "tradeAllowed": true,
  "brokerTime": "2026-09-23 14:02:11.480"
}
```

`brokerTime` is the broker's local time. It isn't UTC; see [Time zones](https://tickwire.io/docs/time-zones/).

## 4. Place an order

```bash
curl -s -X POST "$TW/users/current/accounts/acc_7Qx/trade" \
  -H "auth-token: $TW_KEY" \
  -H "Idempotency-Key: first-order-1" \
  -H "X-Actor: quickstart" -H "X-Reason: trying Tickwire" \
  -H "content-type: application/json" \
  -d '{"actionType": "ORDER_TYPE_BUY", "symbol": "EURUSD", "volume": 0.01}'
```

```json
{
  "numericCode": 10009,
  "stringCode": "TRADE_RETCODE_DONE",
  "message": "Request completed",
  "orderId": "46870472",
  "positionId": "46870472",
  "outcome": "applied"
}
```

Run the same command again: because the `Idempotency-Key` is the same, you get the same answer and
no second position. See [Idempotency](https://tickwire.io/docs/idempotency/).

Some brokers suffix symbols (`EURUSDm`). `GET …/symbols` lists the exact names.

## 5. Close it

```bash
curl -s -X POST "$TW/users/current/accounts/acc_7Qx/trade" \
  -H "auth-token: $TW_KEY" \
  -H "Idempotency-Key: first-close-1" \
  -H "X-Actor: quickstart" -H "X-Reason: done" \
  -H "content-type: application/json" \
  -d '{"actionType": "POSITION_CLOSE_ID", "positionId": "46870472"}'
```

## 6. Watch it live

```bash
# websocat, or any WebSocket client
websocat "wss://api.tickwire.io/users/current/accounts/acc_7Qx/ws?auth-token=$TW_KEY"
{"type":"subscribe","marketData":[{"symbol":"EURUSD","subscriptions":[{"type":"quotes"}]}]}
```

You get a full sync, then `prices` and `health` frames. See [Streaming](https://tickwire.io/docs/streaming/).

## Next

- Coming from another provider? [Change the base URL and key](https://tickwire.io/docs/switching/) and keep your requests.
- Get told about problems: [webhooks](https://tickwire.io/docs/webhooks/).
- Start from working code: [example projects](https://tickwire.io/docs/guides/examples/).