Overview

Welcome to Whaleclub’s API!

You can use the API to programmatically submit new trades, check your balance, fetch your trading history, and much more. The API works with both your live and demo accounts.

The API is organized around REST. All request and response bodies, including errors, are encoded in JSON (application/json content type). All requests must be made over SSL.

Code samples are displayed in the right-side column. All epoch dates are in UTC seconds and amounts in the lowest unit (for BTC, it’s satoshis), unless otherwise indicated.

Authentication

Authenticate by passing your API token in an Authorization header:

curl "https://api.whaleclub.co/v1/balance" -H "Authorization: Bearer API_TOKEN"

All requests to the Whaleclub API must be authenticated.

Authentication is straightforward. Pass your API token as a bearer token in an Authorization header in every request you make.

Authorization: Bearer API_TOKEN

You can get your API token from your API Settings panel which is available from the top right menu in your trading dashboard. You get one token for live trading and another for demo trading.

Replace API_TOKEN with your Whaleclub API token.

Referrals

If you’re using the Whaleclub API as part of an app or service you offer to other traders, you can earn referral commissions when they trade. Pass your Whaleclub Partner ID as a Partner-ID header in all the requests you make. Partner-ID: YOUR_PARTNER_ID You can get your Partner ID from your API Settings panel which is available from the top right menu in your trading dashboard. Only trades with real funds will result in referral commissions. Self-referring and using multiple trading accounts will result in account closure without notice.

Errors
            {
                "error": {
                  "name": "Validation Error",
                  "message": "Please enter a valid amount."
                }
              }
          

The Whaleclub API returns standard HTTP success and error status codes. In case of an error, we’ll include extra information about what went wrong in the JSON-encoded response. If the request is successful, the API will return either a 200 (OK) or a 201 (Created) status code.

Rate limits

Check the headers of any response to see your rate limit status:

                        curl -i "https://api.whaleclub.co/v1/balance"
                        -H "Authorization: Bearer API_TOKEN"
                      
                      HTTP/1.1 200 OK
                      Date: Mon, 27 Feb 2016 21:20:00 GMT
                      Status: 200 OK
                      X-RateLimit-Limit: 60
                      X-RateLimit-Remaining: 54
                      X-RateLimit-Reset: 1488230460
                    

Sample error response – Rate Limit Exceeded (429):

                    {
                        "error": {
                          "name": "Rate Limit Exceeded",
                          "message": "Slow down! You've exceeded the allocated rate limits."
                        }
                      }
                   

The Whaleclub API is rate limited to prevent abuse that would degrade our ability to maintain consistent API performance for all traders. By default, each API token is rate limited at 60 requests per minute. If your requests are being rate limited, you’ll receive a Rate Limit Exceeded error with status code 429. Additionally, requests are throttled up to a maximum of 20 requests per second. You can check the HTTP headers of any response you get from the Whaleclub API to see your current rate limit status.

Client Libraries

Unofficial

PyWhale by logan169 (Python) Whaleclub by askmike (Node.js)

Markets

Request market information for Gold and Apple:

                        curl "https://api.whaleclub.co/v1/markets/XAU-USD,AAPL"
                        -H "Authorization: Bearer API_TOKEN"
                    
                        {
                            "XAU-USD": {
                              "display_name": "Gold",
                              "leverages": [2, 3.3, 5, 10],
                              "limits": {
                                "BTC": 5000000000
                              },
                              "hours": "Sun 5PM - Fri 5PM",
                              "financing_rate": 0.0005,
                              "category": "commodities",
                              "turbo": {
                                "payoff": {
                                  "5": 0.5
                                },
                                "limits": {
                                  "BTC": 10000000
                                }
                              }
                            },
                            "AAPL": {
                              "display_name": "Apple",
                              "leverages": [3.3, 5, 10, 15],
                              "limits": {
                                "BTC": 3000000000
                              },
                              "hours": "Mon-Fri 8AM-5PM",
                              "financing_rate": 0.001,
                              "category": "stocks",
                              "turbo": {
                                "payoff": {
                                  "5": 0.5
                                },
                                "limits": {
                                  "BTC": 10000000
                                }
                              }
                            }
                          } 
                    

Request a list of all available markets:

                            curl "https://api.whaleclub.co/v1/markets"
                            -H "Authorization: Bearer API_TOKEN"
                        
                        {
                            "BTC-USD": {
                              "display_name": "BTC/USD",
                              "category": "crypto"
                            },
                            "EUR-USD": {
                              "display_name": "EUR/USD",
                              "category": "forex"
                            },
                            "USD-JPY": {
                              "display_name": "USD/JPY",
                              "category": "forex"
                            },
                            "XAU-USD": {
                              "display_name": "Gold",
                              "category": "commodities"
                            },
                            "AAPL": {
                              "display_name": "Apple",
                              "category": "stocks"
                            },
                            ...
                          }
                    

Returns market information for one or more markets.

GET https://api.whaleclub.co/v1/markets/:symbol(s) :symbol(s) is a list of one or more comma-separated market symbols. You can request market information for up to 5 markets at once. Omit :symbol(s) to get a list of of available markets with basic information such as display name and category

Price

Request the current price for BTC/USD and EUR/USD:

                        curl "https://api.whaleclub.co/v1/price/BTC-USD,EUR-USD"
                        -H "Authorization: Bearer API_TOKEN"
                    
                        {
                            "BTC-USD": {
                              "bid": 1034.52,
                              "ask": 1035.42,
                              "state": "open",
                              "last_updated": 1486283460
                            },
                            "EUR-USD": {
                              "bid": 1.07846,
                              "ask": 1.07856,
                              "state": "open",
                              "last_updated": 1486283454
                            }
                          }
                    

Returns the current bid and ask prices for one or more markets.

Balance

Request information about your current balance:

                        curl "https://api.whaleclub.co/v1/balance"
                        -H "Authorization: Bearer API_TOKEN"
                    
                        {
                            "available_amount": 1000000000,
                            "total_amount": 1200000000,
                            "unconfirmed_balance": 0,
                            "deposit_address": "1JZZNHDNrXtdfGduRiSXANvBRZhgoa83zo",
                            "active_amount": {
                              "BTC-USD": 400000000,
                              "AAPL": 900000000,
                              "EUR-USD": 4000000000
                            },
                            "pending_amount": {
                              "USD-JPY": 1000000000
                            },
                            "active_amount_turbo": {
                              "EUR-JPY": 10000000,
                              "XAU-USD": 5000000
                            },
                            "last_updated": 1485645703,
                            "currency": "BTC"
                          }
                    
Transactions

List deposits you’ve made to your Whaleclub wallet:

                        curl "https://api.whaleclub.co/v1/transactions/deposits" \
                        -H "Authorization: Bearer API_TOKEN" \
                        -G \
                        --data-urlencode "limit=10"
                    
                        [
                            {
                                "id": "25RDQwc7LpPEFRQPC",
                                "amount": 236427766,
                                "state": "complete",
                                "hash": "a6a5fd411cac34d35f562e8dd65d03173e55d35c58423464400b478b9f408172",
                                "created_at": 1465526999,
                                "currency": "BTC"
                            },
                            {
                                "id": "25RDQwc7LpPEFRQPC",
                                "amount": 100000000,
                                "state": "complete",
                                "hash": "b92841dc4ef1ec589fe717589b14424d792b93d13b56a78cc898cf2fd90005bf",
                                "created_at": 1459560146,
                                "currency": "BTC"
                            },
                            ...
                        ]   
                    
Positions

Sample Position Object:

                        curl "https://api.whaleclub.co/v1/position/s6pGQ4nyS4Z7jHRvJ" \
                        -H "Authorization: Bearer API_TOKEN"
                    
                        {
                            "id": "s6pwQ4nyS4Z7jHRvJ",
                            "slug": "47n2728b3",
                            "direction": "long",
                            "market": "NFLX",
                            "leverage": 10,
                            "type": "limit",
                            "state": "closed",
                            "size": 2000000000,
                            "margin_size": 200000000,
                            "entry_price": 99,
                            "stop_loss": 96.5,
                            "take_profit": 126,
                            "close_reason": "market",
                            "close_price": 122.81,
                            "profit": 481000000,
                            "created_at": 1465795498,
                            "entered_at": 1465795598,
                            "closed_at": 1465799498,
                            "last_updated": 1465797498,
                            "liquidation_price": 91.08,
                            "financing": 120000,
                            "currency": "BTC"
                          }
                    
New Position

Open a 100BTC EUR/USD long position at market price, with a stop-loss and take-profit:

                        curl "https://api.whaleclub.co/v1/position/new" \
                        -H "Authorization: Bearer API_TOKEN" \
                        -X POST \
                        -d 'direction=long' \
                        -d 'market=EUR-USD' \
                        -d 'leverage=100' \
                        -d 'size=10000000000' \
                        -d 'stop_loss=1.07676' \
                        -d 'take_profit=1.08316'
                    
                        {
                            "id": "22bCNkWhiwxF7qAMs",
                            "slug": "vCDQah7Hv",
                            "direction": "long",
                            "market": "EUR-USD",
                            "leverage": 100,
                            "type": "market",
                            "state": "active",
                            "size": 10000000000,
                            "margin_size": 10000000000,
                            "entry_price": 1.07876,
                            "stop_loss": 1.07676,
                            "take_profit": 1.08316,
                            "created_at": 1486327152,
                            "entered_at": 1486327152,
                            "liquidation_price": 1.07013,
                            "currency": "BTC"
                          }
                    

Submit a 50BTC Gold sell stop position at 1050:

                        curl "https://api.whaleclub.co/v1/position/new" \
                        -H "Authorization: Bearer API_TOKEN" \
                        -X POST \
                        -d 'direction=short' \
                        -d 'market=XAU-USD' \
                        -d 'leverage=10' \
                        -d 'size=5000000000' \
                        -d 'entry_price=1050'
                    
                        {
                            "id": "d7gAxDSeLtdYtZsEd",
                            "slug": "GaK75ndGm",
                            "direction": "short",
                            "market": "XAU-USD",
                            "leverage": 10,
                            "type": "stop",
                            "state": "pending",
                            "size": 5000000000,
                            "margin_size": 500000000,
                            "entry_price": 1050,
                            "created_at": 1486307187,
                            "liquidation_price": 1150,
                            "currency": "BTC"
                          }
                    

Submit a 20BTC Netflix limit long position at 99:

                        curl "https://api.whaleclub.co/v1/position/new" \
                        -H "Authorization: Bearer API_TOKEN" \
                        -X POST \
                        -d 'direction=long' \
                        -d 'market=NFLX' \
                        -d 'leverage=10' \
                        -d 'size=2000000000' \
                        -d 'entry_price=99' \
                        -d 'stop_loss=96.5' \
                        -d 'take_profit=126'
                    
                        {
                            "id": "22Eov6G9gXb7cC7n7",
                            "slug": "47n2728b3",
                            "direction": "long",
                            "market": "NFLX",
                            "leverage": 10,
                            "type": "limit",
                            "state": "pending",
                            "size": 2000000000,
                            "margin_size": 200000000,
                            "entry_price": 99,
                            "stop_loss": 96.5,
                            "take_profit": 126,
                            "created_at": 1465795498,
                            "liquidation_price": 91.08,
                            "currency": "BTC"
                          }
                    
Get Position

Fetch an existing position by passing its id to the request:

                        curl "https://api.whaleclub.co/v1/position/s6pGQ4nyS4Z7jHRvJ" \
                        -H "Authorization: Bearer API_TOKEN"
                    
                        {
                            "id": "s6pwQ4nyS4Z7jHRvJ",
                            "slug": "47n2728b3",
                            "direction": "long",
                            "market": "NFLX",
                            "leverage": 10,
                            "type": "limit",
                            "state": "closed",
                            "size": 2000000000,
                            "margin_size": 200000000,
                            "entry_price": 99,
                            "stop_loss": 96.5,
                            "take_profit": 126,
                            "close_reason": "market",
                            "close_price": 122.81,
                            "profit": 481000000,
                            "created_at": 1465795498,
                            "entered_at": 1465795598,
                            "closed_at": 1465799498,
                            "last_updated": 1465797498,
                            "liquidation_price": 91.08,
                            "financing": 120000,
                            "currency": "BTC"
                          }
                    

Fetch information about an existing position.

Request

GET https://api.whaleclub.co/v1/position/:id If the request is successful, the API will return a 200 (Ok) status code.

Update Position

Set stop-loss and take-profit on an existing position:

                    curl "https://api.whaleclub.co/v1/position/update/22bCNkWhiwxF7qAMs" \
                    -H "Authorization: Bearer API_TOKEN" \
                    -X PUT \
                    -d 'stop_loss=1.07576' \
                    -d 'take_profit=1.08726'
                
                    {
                        "id": "22bCNkWhiwxF7qAMs",
                        "slug": "vCDQah7Hv",
                        "direction": "long",
                        "market": "EUR-USD",
                        "leverage": 100,
                        "type": "market",
                        "state": "active",
                        "size": 10000000000,
                        "margin_size": 100000000,
                        "entry_price": 1.07876,
                        "stop_loss": 1.07576,
                        "take_profit": 1.08726,
                        "created_at": 1486327152,
                        "entered_at": 1486327152,
                        "last_updated": 1486367152,
                        "liquidation_price": 1.07013,
                        "currency": "BTC"
                      }
                
Close Position

Close a 100BTC EUR/USD long position at market price:

                    curl "https://api.whaleclub.co/v1/position/close/22bCNkWhiwxF7qAMs" \
                    -H "Authorization: Bearer API_TOKEN" \
                    -X PUT
                
                    {
                        "id": "22bCNkWhiwxF7qAMs",
                        "slug": "vCDQah7Hv",
                        "direction": "long",
                        "market": "EUR-USD",
                        "leverage": 100,
                        "type": "market",
                        "state": "closed",
                        "size": 10000000000,
                        "margin_size": 100000000,
                        "entry_price": 1.07876,
                        "stop_loss": 1.07576,
                        "take_profit": 1.08726,
                        "close_reason": "market",
                        "close_price": 1.08126,
                        "profit": 23000000,
                        "created_at": 1486327152,
                        "entered_at": 1486327152,
                        "closed_at": 1486328121,
                        "last_updated": 1486327452,
                        "liquidation_price": 1.07013,
                        "currency": "BTC"
                      } 
                
Cancel Position
                    curl "https://api.whaleclub.co/v1/position/cancel/d7gAxDSeLtdYtZsEd" \
                    -H "Authorization: Bearer API_TOKEN" \
                    -X PUT
                
                    {
                        "id": "d7gAxDSeLtdYtZsEd",
                        "cancelled": true
                      }
                
Split Position

Split an active 100BTC EUR/USD position into 2 smaller positions of 60BTC and 40BTC:

                            curl "https://api.whaleclub.co/v1/position/split/22bCNkWhiwxF7qAMs" \
                            -H "Authorization: Bearer API_TOKEN" \
                            -X POST \
                            -d 'ratio=60'
                        
                            [
                                {
                                    "id": "RTcdY8cHxeptxZx9Q",
                                    "parent_id": "22bCNkWhiwxF7qAMs"
                                    "slug": "jYFs6Lpno",
                                    "size": 6000000000,
                                    "created_at": 1486327152,
                                    "currency": "BTC"
                                },
                                {
                                    "id": "vM7i73QipKc6F7SFs",
                                    "parent_id": "22bCNkWhiwxF7qAMs",
                                    "slug": "fDVhecYF",
                                    "size": 4000000000,
                                    "created_at": 1486327152,
                                    "currency": "BTC"
                                }
                            ]