# Quickstart

Source: https://docs.pipsocket.com/quickstart

From your workspace's key to an order placed and closed.

You need an MT5 account connected in the [dashboard](https://app.pipsocket.com) (Accounts, then Connect account). Use a demo account while you try things.

## 1. Get your key

Open **API key** in the dashboard and make the workspace's key. It is shown once: copy it and keep it on your server.

```bash
export PIPSOCKET_KEY=psk_...
```

The same page lists your accounts' ids. Take the one you'll trade:

```bash
export ACCOUNT=acc_01m6tx3k9f2qw8r7bznd5yvh4c
```

## 2. Read the account

```bash
curl https://api.pipsocket.com/v1/accounts/$ACCOUNT \
  -H "Authorization: Bearer $PIPSOCKET_KEY"
```

`status` is `connected` once the terminal is logged in to your broker, and `balance`, `equity` and `margin` are from its last report (it reports every second). If `trade_allowed` is `false` (an investor login, for example), MT5 rejects trades.

## 3. Look at the symbol

```bash
curl https://api.pipsocket.com/v1/accounts/$ACCOUNT/symbols/EURUSD \
  -H "Authorization: Bearer $PIPSOCKET_KEY"
```

Note three things from the answer:

- `filling_modes`: the `type_filling` values the symbol allows. There is no default, so you choose one.
- `volume_min`, `volume_max` and `volume_step`: MT5 rejects a volume outside them.
- `execution`: with `instant` or `request`, send a `price` (and a `deviation`); with `market` or `exchange`, MT5 ignores it.

The symbol's name is exactly the broker's: `EURUSD` on one broker can be `EURUSD.r` on another. `GET /symbols` lists them all.

## 4. Place an order

Give the order its own `Idempotency-Key`, and keep it until you have the answer:

```bash
IDEMPOTENCY_KEY=$(uuidgen)

curl -X POST https://api.pipsocket.com/v1/accounts/$ACCOUNT/orders \
  -H "Authorization: Bearer $PIPSOCKET_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "symbol": "EURUSD", "type": "buy", "volume": 0.01, "type_filling": "ioc" }'
```

The answer is the request as recorded for the terminal (`sent`), its `state`, and MT5's answer (`result`):

- `200` with `"state": "done"`: MT5 answered (the trade server, or the terminal refusing to send it). `result.retcode` says how: `10009` (`TRADE_RETCODE_DONE`) is a fill; anything else is a rejection or a partial fill, see [retcodes](/errors#mt5-retcodes).
- `202` with `"state": "pending"`: no answer within 5 seconds. Don't send it again. Look it up with its id:

```bash
curl https://api.pipsocket.com/v1/accounts/$ACCOUNT/requests/req_5f0c2a9e41d7b3a8c6e2f190 \
  -H "Authorization: Bearer $PIPSOCKET_KEY"
```

If the call itself failed (a timeout, a dropped connection), run the same `curl` again with the **same** `$IDEMPOTENCY_KEY`: if the first one was recorded you get it back, and nothing is sent twice. Make a new key only for a new order.

## 5. Close the position

List the open positions and take the position's `ticket`:

```bash
curl https://api.pipsocket.com/v1/accounts/$ACCOUNT/positions \
  -H "Authorization: Bearer $PIPSOCKET_KEY"
```

Then close all of it (or part, with a smaller `volume`):

```bash
IDEMPOTENCY_KEY=$(uuidgen)

curl -X POST https://api.pipsocket.com/v1/accounts/$ACCOUNT/positions/881402311/close \
  -H "Authorization: Bearer $PIPSOCKET_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "volume": 0.01, "type_filling": "ioc" }'
```

## Next

- Get fills, deals and prices as they happen on [the WebSocket stream](/websocket).
- Every call and field is in the [API reference](/api/place-an-order).
- Flatten an account in one call with the [kill switch](/api/kill-switch).