Home Features Markets Blog
Help & FAQ Contact
 
Telegram icon Twitter icon Facebook icon

API Documentation - Version 1.0

This is the documentation for the HTTPS API. Check out our WebSocket API documentation for building real-time applications.

The 1Fox API is in beta. There might be changes in the coming weeks.

Basics

Quota

User

Market

Order

Position



Basics

Technologies

Our API is based on simple HTTPS GET (REST) requests and a WebSocket endpoint. We do not accept requests over unencrypted protocols. Data is always returned as a JSON encoded object. Virtually all programming environments offer the required libraries to access our API. This page only covers the HTTPS API - the documentation for our WebSocket server will be available soon.

Authentication

Some API calls require authentication with an API token. You can generate up to 5 API tokens on your account's "API & Access Management" page. An API token consists of random characters (letters and numbers) and it is important that you do not share this token with untrusted entities.

Base URL

https://1fox.com/api/v1/


Example Request

https://1fox.com/api/v1/type/method.php?&pretty=1&token=YOUR_API_TOKEN
&parameter1=123
&parameter2=false


Example JSON Response

{
	"server_time": "2014-11-06T10:34:47.123456Z",
	"error": false,
	"warning": false,
	"response": {
		...
	}
}


Errors and Warnings

Each request comes with an "error" and "warning" field (boolean). Always check against the "error" field to see if the API request was successful. Make sure to log or display warnings and errors in your application. (e.g. API deprecation warning)

If an error occurs, an "error_code" is returned. Some errors also include an error_data object with additional information.
For warnings, a "_message" post-fixed field exists, which contains a description of the problem.

Example Warning

{
	"server_time": "2016-11-04T10:12:27.631581Z",
	"error": false,
	"warning": true,
	"warning_message": "API version 1 is deprecated and will be disabled on January 9th, 2017. Please switch to version 2 and create a new API token.",
	//Response Object for API request
	"response": {
		...
	}
}

Example Error

{
	"server_time": "2016-11-04T10:12:27.631581Z",
	"error": true,
	"error_code": "TRADE_DECIMALS_LIMIT_PRICE",
	"error_data: {
		"step_size": 1
	}
	"warning": false,
	"response": null
}


Data types

Numeric Types

All integer and float values are returned as quoted strings. This makes sure that no precision is lost across platforms.
"1000315", "102.65557", "-10.98765"

Bitcoin Amounts

Warning: Using 32 bit integers/floats will lead to errors in your application. More information
Bitcoin amounts are returned as strings (see above) and in Bitcoin (1 Bitcoin = 100,000,000 satoshis). (List of Bitcoin Units) Internally, we use integer representation for all amounts, so you can safely multiply amounts by 100.000.000 (1e8) and will always receive a valid (64-bit) integer.
"1", "0.01", "-3.56216842"

Timestamps

Timestamps are returned as ISO 8601 strings with up to microsecond precision. Most modern languages and libraries will handle these without any issues.
The letter 'T' is a separator between the date and time. The letter 'Z' at the end indicates that the timestamp is, like all returned timestamps, in UTC time.
"server_time": "2014-11-06T10:34:47.123456Z"


Paging

Certain API requests like logs have too many elements to request them all at once. Across our API, paging works with a limit and an offset parameter. Here is an example of how to use them:
1st page limit 10, offset 0
2nd page limit 10, offset 10
3rd page limit 10, offset 20
...
n-th page limit 10, offset 10*(n-1)

Example API request with offset 20 and limit 10:

https://1fox.com/api/v1/type/method.php
?token=YOUR_API_TOKEN
&offset=20
&limit=10


Deprecation policy

If an API version is deprecated, a warning message is appended to every response (see example of a warning message above). We will support deprecated APIs for at least one months after a new API version is available. In order to get informed about a deprecated API version in time, please log or display warning messages in your application

SSL certificate verification

We strongly recommend that all API requests validate the SSL certificate presented to prevent MITM attacks. Usually this is turned on by default in most libraries, but if you see a setting to 'verify SSL' you should always ensure it is set to 'true'.

IP Restriction

If you make API requests via a static IP address, make sure to enable an IP restriction when generating the API token, for security reasons.

Pretty Printing

By appending &pretty=1 to a request the response becomes easier readable for humans. In production you should disable this option to save bandwidth and increase parsing times.

Monetizing your software

Monetizing trading software, that was built for other traders on top of our API, can be done in various ways and there are no specific restrictions. However, we strongly recommend to use the possibility of overwriting the trader's referral_id in the order/create method. Per the terms of our referral program, you will receive a profit share once the order gets executed. You can read more about our referral program in the trading panel (login required).

Quotas

In order to keep our API responsive for all traders, we're using an IP address based quota system. The API is rate limited by a CPU allowance, rather than a fixed number of calls per time window. Some API requests take longer to fetch than others, so these cost more allowance. Currently, each client has an allowance of 25000ms (25 seconds) of CPU time per hour. Once that quota is reached no further requests are possible until the start of the next hour. You can check your remaining quota by calling user/quota_status.

Hint: If you often run into the quota, try to minimize requests by using our WebSocket server and the position/merge method.

Execution Time

By appending &execution_time=1 to a request the response will include the execution time for the API call. You can estimate the cpu time/hour cost of your application that way and stay within the quota limits. In production you should disable this option to save bandwidth and increase parsing times.

Example Response

{
	...
	"execution_time_milliseconds": "18.622"
}



Quota


quota/status

Description

Returns the remaining and total CPU allowance time in milliseconds.

Parameters

None

Example Request

https://1fox.com/api/v1/quota/status.php
?pretty=true

Example Response

{
	...
	"response": {
	    "cpu_time_left": "19999600",
	    "cpu_time_left_percentage": "99.998",
	    "cpu_time_total": "20000000"
	}
}


User


user/get

Description

Returns basic user data.

Parameters

None

Example Request

https://1fox.com/api/v1/user/get.php
?token=YOUR_API_TOKEN
&pretty=true

Example Response

{
	...
	"response": {
	    "user_id": "1",
	    "username": "user1",
	    "email_address": "[email protected]",
	    "date_created": "2017-10-01T20:31:55Z",
	    "pending_deposits": "0",
	    "exchange_currency": "USD",
	    "exchange_rate": "1",
	    "notification_unread_count": "0",
	    "profile_image_url": "https://1fox.com/img/trade/profile_default_picture.svg"
	}
}

user/overview

Description

Overview of balance, positions and orders.

Note: Avoid polling this method. Subscribe to the corresponding WebSocket channel which signals user-related updates and call this method when an update happens, instead. This ensures real-time information and minimizes resource usage.

Parameters

None

Example Request

https://1fox.com/api/v1/user/overview.php
?token=YOUR_API_TOKEN
&pretty=true

Example Response

{
	...
	"response": {
	    "balance_unlocked": "4.93500338",
	    "balance_locked": "0.07616479",
	    "positions": {
	        "22": {
	            "position_id": "22",
	            "symbol": "BTCUSD",
	            "direction": "SHORT",
	            "margin": "0.2999991",
	            "margin_total": "0.2999991",
	            "leverage": "10",
	            "balance": "2.999991",
	            "balance_total": "2.999991",
	            "balance_offset": "-0.0006",
	            "contracts": "29700",
	            "contracts_total": "29700",
	            "date_created": "2018-02-01T13:05:26Z",
	            "date_last_trade": "2018-02-01T13:05:26Z",
	            "entry_price": "9900.0002666675",
	            "exit_price": null,
	            "stop_loss_limit": "10760",
	            "stop_loss": "10760",
	            "take_profit": "9260",
	            "profit_loss_unrealized": "-0.144936",
	            "profit_loss_realized": "0",
	            "fees": "-0.0006",
	            "public": false
	        }
	    },
	    "orders": {
	        "39": {
	            "order_id": "39",
	            "position_id": "23",
	            "symbol": "BTCUSD",
	            "type": "LIMIT",
	            "direction": "SHORT",
	            "price": "10500",
	            "margin": "0.07616479",
	            "leverage": "7",
	            "contracts": "5598",
	            "stop_loss": "11860",
	            "take_profit": "9420",
	            "date_created": "2018-01-10T08:48:42Z"
	        }
	    }
	}
}


Market


market/list

Description

Returns the list of available markets.

Parameters

None

Example Request

https://1fox.com/api/v1/market/list.php
?pretty=true

Example Response

{
	...
	"response": {
	    "BTCUSD": {
	        "symbol": "BTCUSD",
	        "currency": "BTC",
	        "decimals": "0",
	        "minimum_price_step": "1",
	        "maximum_leverage": "10",
	        "status": "OPEN",
	        "is_in_market_hours": true
	    },
	    "BTCEUR": {
	        "symbol": "BTCEUR",
	        "currency": "BTC",
	        "decimals": "1",
	        "minimum_price_step": "0.1",
	        "maximum_leverage": "5",
	        "status": "CLOSED",
	        "is_in_market_hours": true
	    }
	}
}

market/get

Description

Returns basic information for the market.

Note: The "decimals" and the "minimum_price_step" fields define the minimum price difference in different representations. Examples:
decimals: 2 => minimum_price_step: 0.01
decimals: 0 => minimum_price_step: 1
decimals: -1 => minimum_price_step: 10

Parameters

symbol string Market symbol.

Example Request

https://1fox.com/api/v1/market/get.php
?pretty=true
&symbol=BTCUSD

Example Response

{
	...
	"response": {
	    "symbol": "BTCUSD",
	    "currency": "BTC",
	    "decimals": "0",
	    "minimum_price_step": "1",
	    "maximum_leverage": "5",
	    "minimum_margin": "0.001",
	    "minimum_margin_public": "0.1",
	    "status": "ORDERS_ONLY",
	    "index_calculation": "Last trading price of Coinbase UK Ltd. (GDAX.COM).",
	    "is_in_market_hours": true,
	    "change_24h_percentage": "4.3315",
	    "volume_24h": "225.84",
	    "seconds_until_next_funding": "181",
	    "date_next_funding": "2017-12-26T20:00:00Z",
	    "estimated_funding_percentage": "0",
	    "index_price": "14210",
	    "date_index": "2017-12-26T19:55:17Z"
	}
}

market/bars

Description

Returns an array of historic market data tuples in the Open, High, Low, Close, Volume format. The "date" field is the beginning of the OHLC interval.

Parameters

symbol string Market symbol.
resolution positive integer Resolution for OHLC market data (in seconds).
date_start date string (ISO8601) (optional) Start date of the returned OHLC interval (Default: earliest date).
date_end date string (ISO8601) (optional) End date of the returned OHLC interval (Default: current date).
limit positive integer (optional) Limits the number of returned data (Default: no limit).

Example Request

https://1fox.com/api/v1/market/bars.php
?pretty=true
&symbol=BTCUSD
&resolution=60
&date_start=2017-11-02T12:00:00Z
&date_end=2017-11-02T13:30:00Z
&limit=250

Example Response

{
	...
	"response": [
	    {
	        "date": "2017-11-02T02:06:00Z",
	        "o": "4000",
	        "h": "4103",
	        "l": "3902",
	        "c": "4068",
	        "v": "15.22"
	    },
	    {
	        "date": "2017-11-02T02:07:00Z",
	        "o": "4100",
	        "h": "4261",
	        "l": "4011",
	        "c": "4204",
	        "v": "8.86"
	    }
	]
}

market/orderbook

Description

Returns the current orderbook.

Parameters

symbol string Market symbol
depth positive integer (optional) Maximum levels of the orderbook. Default: 10, Maximum: 100

Example Request

https://1fox.com/api/v1/market/orderbook.php
?pretty=true
&symbol=BTCUSD
&depth=2

Example Response

{
	...
	"response": {
	    "bids": [
	        {
	            "price": "3700",
	            "contracts": "3698"
	        },
	        {
	            "price": "3600",
	            "contracts": "3600"
	        }
	    ],
	    "asks": [
	        {
	            "price": "4300",
	            "contracts": "898"
	        },
	        {
	            "price": "4400",
	            "contracts": "4400"
	        }
	    ]
	}
}

market/ticker

Description

Returns a basic price ticker containing the fields bid, ask and last.

Parameters

symbols string List of symbols separated by a comma.

Example Request

https://1fox.com/api/v1/market/ticker.php
?pretty=true
&symbols=BTCUSD,BCHUSD

Example Response

{
	...
	"response": {
	    "BTCUSD": {
	        "bid": "10388",
	        "ask": "10400",
	        "last": "10400"
	    },
	    "BCHUSD": {
	        "bid": "8000",
	        "ask": "8003",
	        "last": "7995"
	    }
	}
}

market/index_history

Description

Returns a list of recent index prices for the given market symbol.

Parameters

symbol string Market symbol.
limit limit (optional) Maximum amount of entries per page. Default: 10
offset offset (optional) Offset of how many entries to skip. Default: 0

Example Request

https://1fox.com/api/v1/market/index_history.php
?pretty=true
&symbol=BTCUSD
&limit=10
&offset=0

Example Response

{
	...
	"response": [
	    {
	        "date": "2017-10-03T09:39:00Z",
	        "index_price": "4296.96",
	        "market_price": "4200"
	    },
	    {
	        "date": "2017-10-03T09:40:00Z",
	        "index_price": "4296.66",
	        "market_price": "4200"
	    }
	]
}

market/trades

Description

Returns a list of recent trades for the given market symbol.

Parameters

symbol string Market symbol.
limit limit (optional) Maximum amount of trades. Default: 10

Example Request

https://1fox.com/api/v1/market/trades.php
?pretty=true
&symbol=BTCUSD
&limit=10

Example Response

{
	...
	"response": [
	    {
	        "trade_id": "6",
	        "symbol": "BTCUSD",
	        "type": "BUY",
	        "price": "10200",
	        "contracts": "8159",
	        "volume": "0.79990836",
	        "date": "2018-01-31T13:25:52.748000Z"
	    },
	    {
	        "trade_id": "4",
	        "symbol": "BTCUSD",
	        "type": "BUY",
	        "price": "10100",
	        "contracts": "1010",
	        "volume": "0.1000001",
	        "date": "2018-01-31T13:25:52.736200Z"
	    }
	]
}


Order


order/create

Description

You can create a new order with this API call.
Returns the order_id of the created limit/stop entry order or null if it was a market order.

Parameters

symbol string Market symbol.
margin float Margin (also called "amount" in the user interface) of the order. Gets rounded down to the best possible value to buy/sell an integral number of contracts.
direction string Direction of the order - either "LONG" or "SHORT".
leverage positive integer Value denoting the leverage used for this order.
order_type string Type of the order - either market ("MARKET"), limit ("LIMIT") or stop entry ("STOP_ENTRY").
limit_price float Limit price to be used when opening the order as a limit order - otherwise this parameter will not be used.
stop_entry_price float Stop entry price to be used when opening the order a stop entry order - otherwise this parameter will not be used.
stop_loss float (optional) Stop loss limit for the order, once it has been opened.
take_profit float (optional) Take profit price for the order, once it has been opened.
post_only boolean (optional) (Default: false)

Example Request

https://1fox.com/api/v1/order/create.php
?token=YOUR_API_TOKEN
&pretty=true
&symbol=BTCUSD
&margin=2.345
&direction=SHORT
&leverage=2
&order_type=LIMIT
&limit_price=4300.35
&stop_loss=4200.50
&take_profit=10000

Example Response

{
	...
	"response": {
	    "order_id": "18947"
	}
}

order/close

Description

Returns null on success.

Parameters

order_id positive integer ID of the order to close.

Example Request

https://1fox.com/api/v1/order/close.php
?token=YOUR_API_TOKEN
&pretty=true
&order_id=18947

Example Response

{
	...
	"response": null
}


Position


position/edit

Description

You can edit the stop loss and/or take profit values of a position with this API call.
Returns the details of your changes to the position.

Parameters

position_id positive integer ID of the desired position.
stop_loss float (optional) New stop loss value (Default: stays untouched). Refer to to order/create for detailed information.
take_profit float (optional) New stop loss value (Default: stays untouched). Refer to to order/create for detailed information.

Example Request

https://1fox.com/api/v1/position/edit.php
?token=YOUR_API_TOKEN
&pretty=true
&position_id=4613
&stop_loss=4305.45
&take_profit=4812.36

Example Response

{
	...
	"response": {
	    "position_id": 4613,
	    "stop_loss": 4305.45,
	    "take_profit": 4812.36
	}
}

position/history

Description

Returns the details of all your past/closed positions.

Parameters

limit limit (optional) Maximum amount of entries per page. Default: 10
offset offset (optional) Offset of how many entries to skip. Default: 0

Example Request

https://1fox.com/api/v1/position/history.php
?token=YOUR_API_TOKEN
&pretty=true
&limit=10
&offset=0

Example Response

{
	...
	"response": [
	    {
	        "position_id": "22",
	        "symbol": "BTCUSD",
	        "direction": "SHORT",
	        "margin_total": "0.2999991",
	        "leverage": "10",
	        "balance_total": "2.999991",
	        "contracts_total": "29700",
	        "date_created": "2018-02-01T13:05:26Z",
	        "date_last_trade": "2018-02-01T13:12:37Z",
	        "entry_price": "9900.0002666675",
	        "exit_price": "10491.471131734",
	        "stop_loss": "10760",
	        "take_profit": "9260",
	        "profit_loss_realized": "-0.17098955",
	        "profit_loss_realized_percentage": "-56.99668766",
	        "fees": "-0.00116603",
	        "public": false,
	        "merged_into": null
	    }
	]
}

position/close

Description

Closes the position (with a market order) and all corresponding limit/stop entry orders.

Parameters

position_id positive integer ID of the desired position.

Example Request

https://1fox.com/api/v1/position/close.php
?token=YOUR_API_TOKEN
&pretty=true
&position_id=4613

Example Response

{
	...
	"response": null
}

position/trades

Description

Returns the list of trades for the specified position.

Parameters

position_id positive integer ID of the desired position.
limit limit (optional) Maximum amount of entries per page. Default: 10
offset offset (optional) Offset of how many entries to skip. Default: 0

Example Request

https://1fox.com/api/v1/position/trades.php
?token=YOUR_API_TOKEN
&pretty=true
&position_id=22
&limit=10
&offset=0

Example Response

{
	...
	"response": [
	    {
	        "trade_id": "6",
	        "symbol": "BTCUSD",
	        "position_id": "22",
	        "order_id": null,
	        "price": "10200",
	        "contracts": "8159",
	        "volume": "0.79990836",
	        "type": "BUY",
	        "date": "2018-01-31T13:25:52.748000Z"
	    },
	    {
	        "trade_id": "4",
	        "symbol": "BTCUSD",
	        "position_id": "22",
	        "order_id": null,
	        "price": "10100",
	        "contracts": "1010",
	        "volume": "0.1000001",
	        "type": "BUY",
	        "date": "2018-01-31T13:25:52.736200Z"
	    }
	]
}

position/fees

Description

Returns a list of fees, financing charges and socialized losses that were charged/credited to the specified position.

Parameters

position_id positive integer ID of the desired position.
limit limit (optional) Maximum amount of entries per page. Default: 10
offset offset (optional) Offset of how many entries to skip. Default: 0

Example Request

https://1fox.com/api/v1/position/fees.php
?token=YOUR_API_TOKEN
&pretty=true
&position_id=4613
&limit=10
&offset=0

Example Response

{
	...
	"response": [
	    {
	        "transaction_id": "190",
	        "position_id": "4613",
	        "currency": "BTC",
	        "type": "FEE_TAKER",
	        "amount": "-0.00000198",
	        "percentage": "-0.02",
	        "date": "2018-01-13T14:14:19Z"
	    },
	    {
	        "transaction_id": "165",
	        "position_id": "4613",
	        "currency": "BTC",
	        "type": "SOCIALIZED_LOSS",
	        "amount": "-0.00000099",
	        "percentage": "-0.01",
	        "date": "2018-01-13T14:00:00Z"
	    },
	    {
	        "transaction_id": "164",
	        "position_id": "4613",
	        "currency": "BTC",
	        "type": "FINANCING",
	        "amount": "-0.00000396",
	        "percentage": "-0.04",
	        "date": "2018-01-13T14:00:00Z"
	    },
	    {
	        "transaction_id": "162",
	        "position_id": "4613",
	        "currency": "BTC",
	        "type": "FEE_MAKER",
	        "amount": "0.00000198",
	        "percentage": "0.02",
	        "date": "2018-01-13T13:14:10Z"
	    }
	]
}

position/merge

Description

Merges list of open positions into a single position. Only positions that have the same leverage can be merged. Returns the position ID that positions have been merged into.

Parameters

position_ids string List of position IDs separated by a comma.

Example Request

https://1fox.com/api/v1/position/merge.php
?token=YOUR_API_TOKEN
&pretty=true
&position_ids=21,22,23

Example Response

{
	...
	"response": {
	    "position_id": "22"
	}
}

What are you waiting for?

Create Account Trading Panel

Take us with you

Get it on
Google Play