Deriv’s official API lets you trade programmatically over WebSocket, and the essential flow of any contract revolves around three steps: requesting a price (proposal), buying (buy) and tracking the result (proposal_open_contract). This guide shows, with real, commented Python code, how to chain these calls correctly — including the most common errors that trip up beginners. It is an honest technical reference: the API is powerful, but automating does not mean profiting.

Want a ready-made Python bot connected to the Deriv API to study the code?

See the Python bot and API for Deriv →

Always start with a demo account (virtual token).

Flow overview

The Deriv API is WebSocket-based: you open a connection, authenticate with an API token and exchange JSON messages. To execute a trade you normally follow this sequence:

1. authorize -> authenticates the session with your token 2. proposal -> requests the price/payout of the desired contract 3. buy -> buys using the id returned by the proposal 4. proposal_open_contract -> tracks the contract until it ends
Important: always use the endpoint with your own app_id. Generate a token under API Token in your account settings and start with a demo account token. Never expose the token in public code or repositories.

1. Connection and authorize

Using the websockets library with asyncio, the base of the connection looks like this:

import asyncio, json, websockets APP_ID = “1089” # use your own app_id TOKEN = “YOUR_DEMO_TOKEN” # DEMO account token URL = f”wss://ws.derivws.com/websockets/v3?app_id={APP_ID}” async def call(ws, payload): await ws.send(json.dumps(payload)) return json.loads(await ws.recv()) async def main(): async with websockets.connect(URL) as ws: auth = await call(ws, {“authorize”: TOKEN}) if auth.get(“error”): print(“Auth error:”, auth[“error”][“message”]); return print(“Account:”, auth[“authorize”][“loginid”])

2. proposal — requesting the price

The proposal buys nothing: it returns the entry price (ask_price), the payout and a temporary id that you use to buy. Example of a 60-second CALL contract on a synthetic index:

proposal = await call(ws, { “proposal”: 1, “amount”: 1, # stake amount “basis”: “stake”, “contract_type”: “CALL”, “currency”: “USD”, “duration”: 60, “duration_unit”: “s”, “symbol”: “R_100” # Volatility 100 synthetic index }) if proposal.get(“error”): print(“Proposal error:”, proposal[“error”][“message”]); return prop_id = proposal[“proposal”][“id”] price = proposal[“proposal”][“ask_price”] payout = proposal[“proposal”][“payout”] print(f”Payout: {payout} | Price: {price}”)
Watch the id’s lifetime: the proposal id expires within seconds. If you take too long between the proposal and the buy, you will get an error and will need to request a new proposal.

3. buy — executing the purchase

With the id in hand, the purchase uses the price parameter as the maximum ceiling you accept paying (protection against slippage):

purchase = await call(ws, { “buy”: prop_id, “price”: price # maximum accepted price }) if purchase.get(“error”): print(“Buy error:”, purchase[“error”][“message”]); return contract_id = purchase[“buy”][“contract_id”] print(“Bought! contract_id:”, contract_id)

4. Tracking the result

To know whether you won or lost, subscribe to contract updates with proposal_open_contract and subscribe: 1. Deriv keeps sending messages until the contract closes (is_sold = 1), with the final profit:

await ws.send(json.dumps({ “proposal_open_contract”: 1, “contract_id”: contract_id, “subscribe”: 1 })) while True: msg = json.loads(await ws.recv()) poc = msg.get(“proposal_open_contract”) if not poc: continue if poc.get(“is_sold”): profit = poc[“profit”] status = “WON” if profit > 0 else “LOST” print(f”Result: {status} | Profit: {profit}”) break asyncio.run(main())
Good practice: always handle the error field in every response, manage the req_id when sending several calls in parallel, and respect the API’s request limits so you do not get temporarily blocked.

Common integration errors

The most frequent stumbles are: using a real-account token by mistake (always test on demo first), letting the proposal id expire before the buy, forgetting to handle reconnections when the WebSocket drops, and assuming that “automated means profitable”. The API only executes orders; the decision logic and the risk management remain your responsibility — and they are what determine the outcome.

Frequently asked questions (FAQ)

Is the Deriv API official and free?

Yes, Deriv offers an official, documented WebSocket API, with tokens generated from your own account. Using the API itself costs nothing; you only pay the stake of the trades you choose to make.

Do I need to know how to code to use it?

For the direct API in Python, yes — basic knowledge of Python and asyncio helps a lot. If you do not code, you can use Deriv’s own visual bot builder (DBot) as an alternative.

Can I test without risking money?

Yes. Generate a demo account token and the whole flow (proposal, buy, result) works with virtual balance. That is exactly how you should start.

Does a bot connected to the API guarantee profit?

No. Automation only executes rules with discipline. If the strategy has no statistical edge, the bot will simply lose more consistently. There is no such thing as guaranteed profit.

Disclaimer: binary options and synthetic indices are extremely high-risk products and most retail investors lose money. This content is educational and technical; it does not constitute investment advice or a promise of returns. The code examples are for study purposes and may require adjustments according to Deriv’s current documentation. Always test on a demo account before using any real money and never trade with money you cannot afford to lose.

Similar Posts