Some API calls require your application to authenticate itself. This is done using an API key associated with your account. You can create an API key by visiting the API Keys section on the settings page.

An API key consists of a key id and a key secret. For example, cnz2yjswbv3jd (key id) and 0hydMZDb9HRR3Qq-iqALwZtXLkbLR4fWxtDZvkB9h4I (key secret).

API requests are authenticated using HTTP basic authentication with the key id as the username and the key secret as the password. A missing, incorrect or revoked key causes error 401 to be returned.

Each API key is granted a set of permissions when it is created. The key can only be used to call the permitted API functions.

Permissions

The following is a list of the possible permissions.

• Perm_R_Balance = 1 (View balance)
• Perm_R_Transactions = 2 (View transactions)
• Perm_W_Send = 4 (Send to any address)
• Perm_R_Addresses = 8 (View addresses)
• Perm_W_Addresses = 16 (Create addresses)
• Perm_R_Orders = 32 (View orders)
• Perm_W_Orders = 64 (Create orders)
• Perm_R_Withdrawals = 128 (View withdrawals)
• Perm_W_Withdrawals = 256 (Create withdrawals)
• Perm_W_ClientDebit = 8192 (Debit accounts)
• Perm_W_ClientCredit = 16384 (Credit accounts)
• Perm_R_Beneficiaries = 32768 (View beneficiaries)
• Perm_W_Beneficiaries = 65536 (Create and delete beneficiaries)
• Perm_R_Transfers = 131072 (Create and delete beneficiaries)

A set of permissions is represented as the bitwise OR of each permission in the set. For example the set of permissions required to view balances and orders is Perm_R_Balance | Perm_R_Orders = 33.

When API keys are created, users can select permission sets that automatically include various permissions for their key. These are listed below.

Permission Set	Included Permissions
Read-only access	View Balance View transactions Send to any address View orders View withdrawals View beneficiaries View transfers
Trading access	View Balance View transactions Send to any address View orders View withdrawals View beneficiaries Create orders

Timestamps are always represented as an integer number of milliseconds since the UTC Epoch (a Unix timestamp).

Prices and volumes are always represented as a decimal strings e.g. "123.3432". Strings are used rather than floats to preserve the precision.

Parameters for POST calls are sent as URL-encoded forms (application/x-www-form-urlencoded).

The following currencies are supported through the Luno market platform. For complete details, please see Fees & features:

• XBT: Bitcoin
• BCH: Bitcoin Cash
• ETH: Ethereum
• EUR: Euro
• GBP: Pounds
• LTC: Litecoin
• MYR: Malaysian Ringgit
• NGN: Nigerian Naira
• UGX: Ugandan Shilling
• USDC: USD Coin
• ZAR: South African Rand
• XRP: XRP
• ZMW: Zambian Kwacha

The following are examples of currency pairs that are supported through the Luno market platform. For complete details, please see Fees & Features:

• XBTEUR
• XBTZAR
• XBTUGX
• XBTZMW
• ETHXBT
• BCHXBT

The following methods are available for Funds Withdrawal based on the type of currency or currency pair being withdrawn.

Currency:

• BTC: Bitcoin
• BCH: Bitcoin Cash
• ETH: Ethereum
• LTC: Litecoin
• XRP: XRP

Withdrawal methods:

• ZAR_EFT: EFT
• NAD_EFT: EFT
• KES_EFT: EFT
• KES_MPESA: M-Pesa
• MYR_IBG: Interbank GIRO / IBFT
• IDR_LLG: Bank transfer, Lalu Lintas Giro
• NGN_EFT: Bank transfer
• ZMW_EFT: Bank transfer
• SGD_GIRO: GIRO / FAST
• SGD_WIRE: International Wire
• EUR_SEPA: SEPA transfer
• GBP: Bank transfer
• UGX_EFT: Bank transfer

The Go library is the recommended way to access the API.

The following libraries were implemented by third parties or are no longer under active development and are listed here for convenience. No support is provided by Luno and they may be out of date. A thorough review of the code is recommended before including them in any project.

• Android
• Haskell
• Java
• Node.js
• PHP
• Python
• Ruby

APIs are rate limited to 300 calls per minute. Calls made in excess of this limit will receive a HTTP error Code 429 response.

The streaming API is limited to 50 sessions open simultaneously. Calls in excess of this limit will receive a session limit exceeded message.

Always use HTTPS when calling the API. Non-TLS HTTP requests cause error 403 to be returned. Using non-TLS requests can leak your authentication credentials.

Verify that your client validates the server's SSL certificate. Many libraries (e.g. urllib2 in Python2) do not validate server certificates by default. Failing to verify the server certificate makes your application vulnerable to man-in-the-middle attack.

All transactions on the Luno platform operate on Accounts. Each Account is denominated in a single currency and contains an ordered list of entries that track its running balance.

Each Account has a separate balance and available balance. The available balance may be lower than the balance if some funds have been reserved (e.g. for an open limit order). Account entries affect the balance and available balance independently.

Account entries are numbered sequentially. It is guaranteed that entries are never reordered or deleted. It is also guaranteed that the core attributes of the entry (the running balances and index) are never modified. Therefore, an Account acts as an append-only log of transactions.

Users are able to access information about their beneficiaries - banks or other financial institutions that are able to receive assets.

Market data API calls can be accessed by anyone without authentication. The only exception is Get candles endpoint which does require authentication. The data returned may be cached for up to 1 second. The Streaming API (see below) can be used if lower latency market data is needed.

Trading on the market is done by submitting Orders. After a new Order has been created, it is submitted for processing by the order matching engine. The Order then either matches against an existing order in the order book and is filled or it rests in the order book until it is stopped.

Click here to read more about how order matching works..

Receive addresses are used by cryptocurrencies to send assets to a specific "wallet" or user's account. They are a unique address within the blockchain, so assets sent to that address will only be associated with one wallet.

Users may have multiple receive addresses depending on the number of Accounts they have and what currency is associated with that Account.

Users are able to pre-validate receive addresses under travel rules for cryptocurrency sends from their account.

Users are able to send assets from their accounts to the receive address for a cryptocurrency of the same type as their account. For example, a Bitcoin account can send assets to a Bitcoin receive address, etc.

Sends can be made to cryptocurrency receive addresses.

Warning! Cryptocurrency transactions are irreversible. Please ensure your program has been thoroughly tested before using this call.

Users are able to perform credit and debit operations on their accounts through the API. We refer to these operations as Transfers. Transfers can come through multiple channels, for example: on-chain sends and receives, bank transfers, card payments, etc...

The currently supported transfer methods are:

• ZAR_EFT: EFT
• NAD_EFT: EFT
• KES_EFT: EFT
• KES_MPESA: M-Pesa
• MYR_IBG: Interbank GIRO / IBFT
• IDR_LLG: Bank transfer, Lalu Lintas Giro
• NGN_EFT: Bank transfer
• ZMW_EFT: Bank transfer
• SGD_GIRO: GIRO / FAST
• SGD_WIRE: International Wire
• EUR_SEPA: SEPA transfer
• GBP: Bank transfer
• UGX_EFT: Bank transfer

Withdrawals and on-chain sends are debit (outbound) Transfers on the user account. Deposits and on-chain receives are credit (inbound) Transfers on the user account.

For on-chain transfers field transaction_id will be populated to facilitate record reconciliation.

The websocket API provides streaming access to data such as market data or user data (e.g. order fills). It is more efficient and provides lower latency information than repeatedly polling the order book and recent trades, but is more complicated to implement.

The streaming protocol works by requiring the client to keep an in-memory record of the streamed data, such as the order book. Update messages are then sent from the server and the client uses these to update its copy of the order book. When applied correctly, the client's view of the order book will be identical to the server's view.

Market stream

Protocol

The client state consists of the following data:

• sequence number
• set of bid orders (id, price, volume)
• set of ask orders (id, price, volume)
• list of trades
• market status

Each update message transmitted from the server has a unique increasing sequence number. The message with sequence number n can be applied to state sequence n-1 to produce state sequence n.

A message may contain multiple updates which must be applied atomically and in order.

If an update is received out-of-sequence (for example update sequence n+2 or n-1 received after update sequence n), the client cannot continue and must reinitialise the state.

There are four types of update:

• Create
• Delete
• Trade
• Status

Create

Add a bid or ask Order to the Order Book with a given id, price and volume. For example:

{
  "order_id": "BXMC2CJ7HNB88U4",
  "type": "BID",
  "price": "1234.00",
  "volume": "1.23"
}

Delete

Remove the order from the order book with a given id. For example:

{
  "order_id": "BXMC2CJ7HNB88U4"
}

Trade

Reduce the outstanding volume of an Order in the Order Book (maker_order_id) and append a Trade to the Trades List. For example:

{
  "sequence": 24509303,
  "base": "0.1",
  "counter": "5232.00",
  "maker_order_id": "BXMC2CJ7HNB88U4",
  "taker_order_id": "BXMC2CJ7HNB88U5"
}

Status

Set the status of the market to the given value. For example:

{
  "status": "POSTONLY",
}

Examples

A new order is placed below market

In this case, an update message is sent with a single create update.

A market order is placed that is immediately filled

In this case, an update message is sent containing multiple trade updates. There will be no create update since the new order never enters the order book.

An order is placed that is partially filled

In this case, the update message contains multiple trade updates and a single create update. The volume in the create update is the remaining volume for the order.

An order is stopped

In this case, the update message contains a single delete update.

The market switches to post-only and trading is suspended

In this case, the update message contains a single status update.

Websockets

The streaming updates protocol described above can be accessed using websockets. The server sends the current order book state, and then sends update messages as quickly as possible. Both the client and server must send regular keep alive messages to avoid disconnection during periods of low update message activity.

Connect to the websocket server at: wss://ws.luno.com/api/1/stream/:pair

The client must start by sending API key credentials:

{
  "api_key_id": "abcdef",
  "api_key_secret": "api_key_secret_goes_here"
}

The server will then send the current order book in the following format:

{
  "sequence": "24352",
  "asks": [
    {
      "id": "BXMC2CJ7HNB88U4",
      "price": "1234.00",
      "volume": "0.93"
    }
  ],
  "bids": [
    {
      "id": "BXMC2CJ7HNB88U5",
      "price": "1201.00",
      "volume": "1.22"
    }
  ],
  "status": "ACTIVE",
  "timestamp": 1528884331021
}

The server then sends messages like the following:

{
  "sequence": "24353",
  "trade_updates": null, // array of 0 or more trade updates
  "create_update": null, // null or 1 create update
  "delete_update": null, // null or 1 delete update
  "status_update": null, // null or 1 status update
  "timestamp": 1469031991
}

An empty message is a keep alive message. Ping/Pong messages are supported.

If there is any error while processing an update (e.g. an out-of-order update) or there is a network error or timeout (e.g. keep alive message not received in time), the client should close the connection and reconnect in order to reinitialise its state. It is important that clients implement some kind of backoff to avoid being rate limited in case of errors.

User stream

Protocol

There are three types of update:

• Order Status
• Order Fill
• Balance Update

Order Status

Update the status of an order. For example:

{
  "order_id": "BXGMHMJXVEZK6NS",
  "client_order_id": "sample-XYZ",
  "market_id": "XBTZAR",
  "status": "AWAITING"
}

The possible values for status are AWAITING, PENDING and COMPLETE.

Order Fill

Update the fill data of an order. For example:

{
  "order_id": "BXGMHMJXVEZK6NS",
  "client_order_id": "sample-XYZ",
  "market_id": "XBTZAR",
  "base_fill": "1.00000000",
  "counter_fill": "100.00000000",
  "base_delta": "0.40000000",
  "counter_delta": "40.00000000",
  "base_fee": "0.00100000",
  "counter_fee": "0.10000000",
  "base_fee_delta": "0.00040000",
  "counter_fee_delta": "0.04000000"
}

Balance Update

Latest account balance status:

{
  "account_id": 8203463422864003664",
  "row_index": 1,
  "balance": "100.00000000",
  "balance_delta": "100.00000000",
  "available": "99.00000000",
  "available_delta": "1.00000000"
}

Websockets

The streaming updates protocol described above can be accessed using websockets. The server sends update messages as quickly as possible.

Connect to the websocket server at: wss://ws.luno.com/api/1/userstream

The client must start by sending API key credentials:

{
  "api_key_id": "abcdef",
  "api_key_secret": "api_key_secret_goes_here"
}

The server then sends messages like the following:

{
  "type": "order_status",
  "timestamp": 1469031991,
  "order_status_update": null, // null or 1 order status update
  "order_fill_update": null, // null or 1 order fill update
  "balance_update": nill, // null or balance update
}

The possible values for type are order_status, order_fill, balance_update.

Ping/Pong messages are supported.

It is important that clients implement some kind of backoff to avoid being rate limited in case of errors.

The server keeps a cache of all messages sent in the last 5 minutes. When reconnecting, messages generated while the client was disconnected will be resent to ensure messages are not missed. Note that staying disconnected for longer than 5 minutes will discard the message cache.

This section describes the error codes in more detail.

• ErrInvalidArguments If any request parameters have invalid values this error will be returned. This error should also include a list of the offending fields to help identify and fix any issues.
• ErrTravelRule Please ensure that you've initiated a once-off crypto send for this specific wallet address via the website or mobile app and included relevant Travel Rule information before trying again via the send API. Click here for more information on the Travel Rule.

• 2024-02-21:
  • Added transfer_id field to the Withdrawal response object
• 2023-12-04:
  • Added base_account_id and counter_account_id fields to the OrderV2 object
• 2022-06-23:
  • Added client_order_id in Balance Stream section
  • Added "time_in_force" parameter to POST /api/1/postorder endpoint
  • Added "time_in_force" to GET orders/:id responses
  • Added "time_in_force" to GET listorders responses
  • Updated Market documentation to reflect GET /api/exchange/1/candles call is authenticated
• 2021-12-22: Added Balance Stream section.
• 2021-10-29: Added User Stream section.
• 2021-10-22: Add support for 1m candles for the GET /api/exchange/1/candles endpoint.
• 2021-08-04: Add Error Codes section along with restrictions to users in jurisdiction with money travel rules.
• 2021-02-18: Add GET /api/exchange/1/transfers to list deposits and withdrawals.
• 2020-08-20: Removed Lightning API section.
• 2020-06-22: Updated domain to api.luno.com
• 2020-02-24: Added optional destination_tag and has_destination_tag parameter to POST /api/1/send to support XRP sends. Please note, not specifying has_destination_tag parameters to POST /api/1/send to support XRP sends with destination tags. Please see https://xrpl.org/source-and-destination-tags.html to learn more about XRP destination tags.
• 2020-02-12: Added PUT /api/1/accounts/:id/name to allow updating of an account name.
• 2019-11-21: Added GET /api/1/beneficiaries to allow listing of bank beneficiaries.
• 2018-07-16: Added aggregated order book API. Rate limits for market data have been increased to 1 per second. Market data may be cached for up to 1 second.
• 2018-06-29: Add post_only parameter to POST /api/1/postorder.
• 2018-06-15: Update PHP and Python SDK URLs.
• 2018-06-13: Added timestamp to the orderbook streamer response.
• 2018-06-08: Update Go SDK URL.
• 2017-12-23: Added maker_order_id and taker_order_id to streaming trade updates. Deprecated order_id.
• 2017-10-31: OAuth2 is no longer available for new applications.
• 2017-10-16: Updated /api/1/trades to only return BID or ASK types and it may now lag behind latest data.
• 2017-07-02: Updated websocket server to wss://ws.luno.com.
• 2017-03-02: Added /api/1/fee_info which returns your fees and 30 day trading volume.
• 2016-11-21: The /api/1/trades now returns at most 100 results per call.
• 2016-11-01: Removed 50 receive address create limit on POST /api/1/funding_address to allow unlimited receive addresses per account. Address creation is rate limited to 1 per hour, allowing for bursts of up to 10 consecutive calls.
• 2016-08-10: Added GET /api/1/listtrades to allow listing of recent trades. Please note that trades will soon be removed from the response of GET /api/1/listorders GET /api/1/orders/:id.
• 2016-08-05: Added beta Streaming API section
• 2016-07-25: Added optional beneficiary_id parameter to POST /api/1/withdrawals.
• 2016-05-29: Error code 429 may be returned when exceeding rate limits. This will become the default as of 2016-07-01.
• 2016-04-04: Added completed_timestamp field to GET /api/1/listorders and GET /api/1/orders/:id responses.
• 2016-02-05: Added optional since parameter to GET /api/1/trades and added is_buy field to the response.
• 2015-09-14: Added POST /api/1/marketorder to allow placing of market orders.
• 2015-07-29: Added Perm_R_Beneficiaries and Perm_W_Beneficiaries permissions. You will have to generate a new API key if you require these permissions.
• 2015-06-08: Renamed GET /api/1/withdrawals/ to GET /api/1/withdrawals and POST /api/1/withdrawals/ to POST /api/1/withdrawals to be more consistent with other endpoints. The old URLs are now deprecated.
• 2015-05-28: Added POST accounts for creating additional accounts in specified currencies.
• 2015-05-07: Added the "Name" field to the "Balance" response
• 2015-04-25:
  • Added the "Accounts" section.
  • Added the account transactions and pending transactions calls.
  • Added the "Permissions" section.
  • Documented which permissions are required for each call.
  • Updated description of the "send" call. A pin is no longer required.
  • Added "name" parameter to POST /api/1/funding_address.
• 2015-03-27: Return a list of trades for an order on GET orders/:id if the order has any trades.
• 2015-01-30: Clarified the interpretation of base, counter, base_fee and counter_fee in the list_orders response in the case where counter_fee is nonzero for buy orders and where base_fee is nonzero for sell orders.
• 2014-12-17: The amount parameter for withdrawal requests now excludes the withdrawal fee.
• 2014-12-12:
  • Added the new Quotes API.
  • The transactions beta call has been deprecated.
• 2014-12-04: The balance method can now be called with no arguments to return all account balances.
• 2014-08-26:
  • Added Send API call.
  • Added OAuth2 API.
• 2014-06-10: Orders placed through the API are no longer subject to different limits than those placed through the website.
• 2014-06-02:
  • You can now create multiple API keys with different permissions (e.g. read-only, read/write).
  • Added calls to list, create, get and cancel withdrawal requests.
  • Added link to Android client library.
• 2014-05-29:
  • The preferred host name for API calls has changed to api.mybitx.com.
  • Added experimental call to retrieve transactions list.
  • Added call to allocate new receive addresses.
  • Receive address call now returns the amount received by that address.
  • You can now request listorders to return only the list of open orders.
• 2014-04-15: Previously orders created through the API would expire after 24 hours. Now, orders created through the API do not expire. The behaviour is now the same as for orders placed through the website.
• 2014-01-25:
  • A new funding_address call has been added to get the bitcoin address you need to fund your trade account balance.
• 2014-01-21:
  • The API has been extended to support multiple asset pairs.
  • A new balance call has been added to query the trading account balance.
  • All URLs have been renamed from /api/1/BTCZAR/x to /api/1/x?pair=XBTZAR. The old URLs are now deprecated.
  • getlimits: This call has been deprecated. Please use the new balance call instead.
  • ticker: The currency field is now deprecated.
  • orderbook: The currency field is now deprecated.
  • trades: The currency field is now deprecated.
  • listorders: The btc, zar, fee_btc and fee_zar fields are now deprecated. Please use base, counter, fee_base, fee_counter fields instead.
  • The embedded market indicator has been removed since nobody is using it.
  • All deprecated features will continue to work for two months.
• 2014-01-06:
  • listorders: Added fee_btc and fee_zar fields.
  • listorders: Removed SETTLEMENT state (it's no longer relevant).
  • ticker: Removed mtgox_price (use Mt Gox's API directly instead).