What is the operatorId and why is it required? – Bitvavo Help Center

Summary

This article explains what the operatorId parameter is, why it's required by regulation, and how to use it correctly when placing API orders through Bitvavo. If you're using bots or scripts to trade via API, this article will help you understand how to assign and implement the operatorId in the body of the request properly.

What is the operatorId?

The operatorId is a required parameter for API requests involving trading actions, such as placing an order. This is introduced as part of crypto regulations and helps identify which individual, bot, or script within your account submitted a particular order.

This is an integer type key, and is not provided by Bitvavo. You can set this value yourself. We recommend a value between 1 and 9,223,372,036,854,775,807.

If you are running multiple trading bots or scripts under one API key, adding the operatorId allows you to track which entity placed which order.

Why is it mandatory?

New crypto compliance rules require platforms like Bitvavo to help you (and regulators) keep a clear audit trail of trading activity. The operatorId:

Identifies who or what placed the order within your account
Is required for each trading request
Cannot be left out or opted out of
Is a unique integer for every bot/system sending requests within your account

How to use the operatorId

The operatorId is an int64 number (a whole number, not a string). You must generate and assign it yourself. For example, you can choose 12234 for one bot, and 12235 for another.

Tip: Choose a unique operatorId for each bot or script to keep a clear log of which component sent the order.

Here’s how to implement it:

When you make a POST /order API call (or other trading endpoints), add the operatorId in the body of the request.
Make sure you send it as a number, not a string.

✅ Correct: "operatorId": 12234
❌ Incorrect: "operatorId": "12234"

Update all your trading endpoints to include the operatorId parameter.

Where can I find examples?

You can find the full example in our API documentation for the Create Order endpoint.

Below is a simplified version showing how to correctly include the operatorId:

{
  "market": "BTC-EUR",
  "side": "buy",
  "orderType": "limit",
  "amount": "0.1",
  "price": "25000",
  "operatorId": 12234
}

Make sure the operatorId is added in the request body and that it's a number (without quotes). If sent incorrectly, your order will be rejected.

Tip: You can test your API requests in the Bitvavo test environment first to avoid issues in production.

Frequently asked questions

Do I have to use a different operatorId for every order?

No, you can reuse the same operatorId for all orders from the same bot or script. The idea is to distinguish between different trading components, not individual trades.

What happens if I send the operatorId as a string?

The order will likely fail. Make sure the operatorId is sent as a number (int64), not in quotes.

Is there a default operatorId if I don’t set one?

No, you must always set an operatorId yourself. There is no fallback or default value.

Summary