pipsocketDOCS
Guides / Get started

Quickstart

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

You need an MT5 account connected in the dashboard (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.

export PIPSOCKET_KEY=psk_...

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

export ACCOUNT=acc_01m6tx3k9f2qw8r7bznd5yvh4c

2. Read the account

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

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:

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.
  • 202 with "state": "pending": no answer within 5 seconds. Don't send it again. Look it up with its id:
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:

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):

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