MAX Exchange API Ruby SDK

Gem Version Build Status RubyGems Code Climate Test Coverage

A ruby implementation of MAX exchange API

  • REST API V2
  • Websocket API

Documentations

Supports

  • Ruby 2.2 ~ 2.7, 3.0 ~ 3.3

Table of contents

Installation

gem 'max_exchange_api'

And then execute:

$ bundle

Or install it yourself as:

$ gem install max_exchange_api

Usage

@public_v3_api = MaxExchangeApi::PublicV3Api.new
@public_v3_api.depth('usdttwd')

access_key, secret_key = File.read('secret').split(',')
@private_v3_api = MaxExchangeApi::PrivateV3Api.new(access_key, secret_key)
@private_v3_api.create_order!('usdttwd', 'sell', 1000, price: 31.35)
@private_v3_api.create_order!('usdttwd', 'buy', 1000, price: 31.15)

Configuration

Set timeout time

# Set default timeout time
MaxExchangeApi.default_config.timeout = 3 # seconds

# Create an api instance with custom timeout time
api = MaxExchangeApi::PublicV3Api.new(config: { timeout: 12 })
api = MaxExchangeApi::PrivateV3Api.new(access_key, secret_key, config: { timeout: 12 })

Logging

require 'logger'

# Print log to standard output
MaxExchangeApi.default_config.logger = Logger.new(STDOUT)

# Print log to file
MaxExchangeApi.default_config.logger = Logger.new('log/api.log')

# Create an api instance with custom logger
api = MaxExchangeApi::PublicV3Api.new(config: { logger: Logger.new(STDOUT) })
api = MaxExchangeApi::PrivateV3Api.new(access_key, secret_key, config: { logger: Logger.new(STDOUT) })

Switch Sub-Account

@private_v3_api = MaxExchangeApi::PrivateV3Api.new(access_key, secret_key)

# Switch to a specific sub-account (e.g., 's1-a7f20f')
@private_v3_api.current_sub_account_sn = 's1-a7f20f'

# Use the default sub-account (determined by the API token owner)
@private_v3_api.current_sub_account_sn = nil

# Switch to the main account
@private_v3_api.current_sub_account_sn = 'main'

Public V3 Api Examples

@public_v3_api = MaxExchangeApi::PublicV3Api.new

GET /api/v3/wallet/m/index_prices

Get latest index prices of m-wallet

@public_v3_api.index_prices

GET /api/v3/wallet/m/historical_index_prices

Get latest historical index prices

@public_v3_api.index_prices_histories

GET /api/v3/wallet/m/limits

Get total available loan amount

@public_v3_api.available_loan_amount

GET /api/v3/wallet/m/interest_rates

Get latest interest rates of m-wallet

@public_v3_api.loan_interest_rates

GET /api/v3/markets

Get all available markets.

@public_v3_api.markets

GET /api/v3/currencies

Get all available currencies

@public_v3_api.currencies

GET /api/v3/timestamp

Get server current time, in seconds since Unix epoch

@public_v3_api.timestamp

GET /api/v3/k

Get OHLC(k line) of a specific market.

# use default parameters
@private_v3_api.k('btctwd')

# provide all possible parameters
@private_v3_api.k('btctwd', limit: 30, period: 1, timestamp: 1624705402)

GET /api/v3/depth

Get depth of a specified market.

# use default parameters
@private_v3_api.depth('maxtwd')

# provide all possible parameters
@private_v3_api.depth('maxtwd', limit: 10, sort_by_price: true)

GET /api/v3/trades

Get recent trades on market, sorted in reverse creation order.

# use default parameters
@private_v3_api.trades('btctwd')

# provide all possible parameters
@private_v3_api.trades(
  'maxtwd', 
  timestamp: 1624705402,
  limit: 15,
)

GET /api/v3/tickers

Get ticker of all markets.

@private_v3_api.tickers

GET /api/v3/ticker

Get ticker of specific market.

@private_v3_api.ticker('btctwd')

Private V3 Api Examples

access_key = 'YOUR_ACCESS_KEY'
secret_key = 'YOUR_SECRET_KEY'

@private_v3_api = MaxExchangeApi::PrivateV3Api.new(access_key, secret_key)

User

GET /api/v3/info

Get user information

@private_v3_api.member_info

Account

GET /api/v3/wallet/wallet_type/accounts

Get your account balance with all supported currencies by different wallet type

@private_v3_api.accounts

# provide all possible parameters
@private_v3_api.accounts(wallet_type: 'm', currency: 'usdt')

M-Wallet

GET /api/v3/wallet/m/ad_ratio

Get the latest AD ratio of your m-wallet

@private_v3_api.m_wallet_ad_ratio

POST /api/v3/wallet/m/loan

Create a loan request for your m-wallet

@private_v3_api.m_wallet_loan!('30000', 'usdt')

POST /api/v3/wallet/m/repayment

Make a repayment for your loan

@private_v3_api.m_wallet_repay!('30000', 'usdt')

GET /api/v3/wallet/m/loans

Get loan history of your m-wallet

@private_v3_api.m_wallet_loans('usdt')

# provide all possible parameters
@private_v3_api.m_wallet_loans(
  'usdt',
  timestamp: 1624705402,
  order_by: 'asc',
  limit: 15,
)

GET /api/v3/wallet/m/repayments

Get repayment history of your m-wallet

@private_v3_api.m_wallet_repayments('usdt')

# provide all possible parameters
@private_v3_api.m_wallet_repayments(
  'usdt',
  timestamp: 1624705402,
  order_by: 'asc',
  limit: 15,
)

GET /api/v3/wallet/m/liquidations

Get liquidation history of your m-wallet

@private_v3_api.m_wallet_liquidations

# provide all possible parameters
@private_v3_api.m_wallet_liquidations(
  timestamp: 1624705402,
  order_by: 'asc',
  limit: 15,
)

GET /api/v3/wallet/m/liquidation

Get detail of one specific liquidation history of your m-wallet

@private_v3_api.m_wallet_liquidation('210407080800050666')

GET /api/v3/wallet/m/interests

Get interest history of your m-wallet

@private_v3_api.m_wallet_interests('usdt')

# provide all possible parameters
@private_v3_api.m_wallet_interests(
  'usdt',
  timestamp: 1624705402,
  order_by: 'asc',
  limit: 15,
)

Convert

GET /api/v3/converts

Get convert orders history

@private_v3_api.convert_orders

# provide all possible parameters
@private_v3_api.convert_orders(
  timestamp: 1624705402,
  order_by: 'asc',
  limit: 15,
)

GET /api/v3/convert

Get details of a specific convert order

@private_v3_api.convert_order('6322d9bd-736b-4f19-b862-829e75cae1ce')

POST /api/v3/convert

Execute a convert (flash exchange) between two currencies

# Specify from amount
@private_v3_api.create_convert_order(
  from: ['0.52', 'usdt'],
  to: [nil, 'twd'],
)

# Specify to amount
@private_v3_api.create_convert_order(
  from: [nil, 'usdt'],
  to: ['16.58', 'twd'],
)

Order

GET /api/v3/wallet/wallet_type/orders/open

Get open orders.

# use default parameters
@private_v3_api.open_orders('maxtwd')

# provide all possible parameters
@private_v3_api.open_orders(
  'maxtwd',
  wallet_type: 'm', # 'spot' or 'm'
  timestamp: 1773734452000,
  order_by: 'desc',
  limit: 15,
)

GET /api/v3/wallet/wallet_type/orders/closed

Get closed orders.

# use default parameters
@private_v3_api.closed_orders('maxtwd')

# provide all possible parameters
@private_v3_api.closed_orders(
  'maxtwd',
  wallet_type: 'm', # 'spot' or 'm'
  timestamp: 1773734452000,
  order_by: 'desc',
  limit: 15,
)

GET /api/v3/wallet/wallet_type/orders/history

Get order history in ascending order from a specific from_id.

# use default parameters
@private_v3_api.order_history('maxtwd')

# provide all possible parameters
@private_v3_api.orders_history(
  'maxtwd',
  wallet_type: 'm', # 'spot' or 'm'
  from_id: 123456,
  limit: 15,
)

POST /api/v3/wallet/wallet_type/order

Create sell/buy order

# use default parameters
@private_v3_api.create_order!('maxtwd', 'buy', 1000, price: 7.5)

# provide all possible parameters
@private_v3_api.create_order!(
  'maxtwd',
  'buy',
  1000,
  wallet_type: 'm', # 'spot' or 'm'
  price: 7.5,
  client_oid: 'MY_ORDER_ID_12345',
  stop_price: 8,
  ord_type: 'limit',
  group_id: 12345678,
)

GET /api/v3/order

Get order detail

# use default parameters
# use max unique order id
@private_v3_api.order(123456)

# use user specified order id
@private_v3_api.order(client_oid: 'MY_ORDER_123456')

DELETE /api/v3/wallet/wallet_type/order

Cancel all orders

# use default parameters
@private_v3_api.cancel_orders!

# provide all possible parameters
@private_v3_api.cancel_orders!(
  wallet_type: 'm', # 'spot' or 'm'
  market: 'maxtwd', 
  side: 'sell',
  group_id: '123456',
)

DELETE /api/v3/order

Cancel an order

# use max unique order id
@private_v3_api.cancel_order!(123456)

# use user specified order id
@private_v3_api.cancel_order!(client_oid: 'MY_ORDER_123456')

Trade

GET /api/v3/order/trades

Get trade detail by your order info

# use max unique order id
@private_v3_api.my_trades_of_order(123456)

# use user specified order id
@private_v3_api.my_trades_of_order(client_oid: 'MY_ORDER_123456')

GET /api/v3/wallet/path_wallet_type/trades

Get executed trades

# use default parameters
@private_v3_api.my_trades

# provide all possible parameters
@private_v3_api.my_trades(
  wallet_type: 'm', # 'spot' or 'm'
  market: 'maxtwd',
  timestamp: 1624705402,
  from_id: 68444,
  order_by: 'asc',
  limit: 15,
)

Deposit

GET /api/v3/deposit_address

Get user deposit address by currency version

@private_v3_api.deposit_address('bscusdt')

GET /api/v3/deposits

get your deposits history

# use default parameters
@private_v3_api.deposits

# provide all possible parameters
@private_v3_api.deposits(
  currency: 'max',
  timestamp: 1624705402,
  order_by: 'asc',
  limit: 15,
)

GET /api/v3/deposit

Get details of a specific deposit

# Query by uuid
@private_v3_api.deposit(uuid: '18022603540001')

# Query by txid
@private_v3_api.deposit(txid: '0x8daa98e07886985bd6a142cd81b83582d6085f7eb931dc4984c18c84f2a845e0')

Withdraw

GET /api/v3/withdraw_addresses

Get withdraw addresses of spot wallet

@private_v3_api.withdraw_addresses('usdt')

# provide all possible parameters
@private_v3_api.withdraw_addresses('usdt', limit: 10, offset: 5)

GET /api/v3/withdrawals

Get external withdrawals history

# use default parameters
@private_v3_api.withdraws

# provide all possible parameters
@private_v3_api.withdraws(
  currency: 'max',
  state: 'done',
  timestamp: 1624705402,
  order_by: 'asc',
  limit: 15,
)

GET /api/v3/withdrawal

Get details of a specific external withdraw

# Query by uuid
@private_v3_api.withdraw(uuid: '18022603540001')

POST /api/v3/withdrawal

Submit a crypto withdrawal. IP whitelist for api token is required.

@private_v3_api.create_withdraw!('withdraw_address_id', 100000)

POST /api/v3/withdrawal/twd

Submit twd withdrawal to verified bank account. IP whitelist for api token is required.

@private_v3_api.create_twd_withdraw!(100000)

Internal Transfer

GET /api/v3/internal_transfers

Get internal transfers history

# use default parameters
@private_v3_api.internal_transfers

# provide all possible parameters
@private_v2_api.internal_transfers(
  currency: 'btc',
  side: 'in',
  timestamp: 1624705402,
  order_by: 'asc',
  limit: 15,
)

Reward

GET /api/v3/rewards

Get internal transfers history

# use default parameters
@private_v3_api.rewards

# provide all possible parameters
@private_v2_api.rewards(
  currency: 'btc',
  reward_type: 'yield',
  timestamp: 1624705402,
  order_by: 'asc',
  limit: 15,
)

SubAccount

GET /api/v3/sub_accounts

Get sub_accounts

@private_v3_api.sub_accounts

GET /api/v3/sub_account

Get sub_account

@private_v3_api.sub_account('s1-a7f20f')

POST /api/v3/sub_accounts

Create sub_account

@private_v3_api.create_sub_account!(name: 'My Test SubAccount')

PUT /api/v3/sub_account

Update sub_account

@private_v3_api.update_sub_account!('s1-a7f20f', name: 'My Test SubAccount')

DELETE /api/v3/sub_account

Delete sub_account

@private_v3_api.delete_sub_account!('s1-a7f20f')

POST /api/v3/sub_account/transfer

Submit sub_account transfer

# Transfer from main to s1 sub-account
@private_v3_api.current_sub_account_sn = 'main'
@private_v3_api.create_sub_account_transfer!('s1-a7f20f', 3, 'eth')

# Transfer from s1 sub-account to s2 sub-account
@private_v3_api.current_sub_account_sn = 's1-a7f20f'
@private_v3_api.create_sub_account_transfer!('s2-jsjwsa', 3, 'eth')

Public V2 Api Examples

@public_v2_api = MaxExchangeApi::PublicV2Api.new

GET /api/v2/vip_levels

Get all VIP level fees.

@public_v2_api.vip_levels

GET /api/v2/vip_levels/level

Get VIP level fee by level.

@public_v2_api.vip_levels(2)

GET /api/v2/currencies

Get all available currencies.

@public_v2_api.currencies

GET /api/v2/k

Get OHLC(k line) of a specific market.

# use default parameters
@public_v2_api.k('btctwd')

# provide all possible parameters
@public_v2_api.k('btctwd', limit: 30, period: 1, timestamp: 1624705402)

GET /api/v2/depth

Get depth of a specified market.

# use default parameters
@public_v2_api.depth('maxtwd')

# provide all possible parameters
@public_v2_api.depth('maxtwd', limit: 10, sort_by_price: true)

GET /api/v2/trades

Get recent trades on market, sorted in reverse creation order.

# use default parameters
@public_v2_api.trades('btctwd')

# provide all possible parameters
@public_v2_api.trades(
  'maxtwd', 
  timestamp: 1624705402,
  from: 68444,
  to: 69444,
  order_by: 'asc',
  pagination: true,
  page: 3,
  limit: 15,
  offset: 5,
)

GET /api/v2/markets

Get all available markets.

@public_v2_api.markets

GET /api/v2/summary

Overview of market data for all tickers.

@public_v2_api.summary

GET /api/v2/tickers/path_market

Get ticker of specific market.

@public_v2_api.tickers('btctwd')

GET /api/v2/tickers

Get ticker of all markets.

@public_v2_api.tickers

GET /api/v2/timestamp

Get server current time, in seconds since Unix epoch.

@public_v2_api.timestamp

Private V2 Api Examples

access_key = 'YOUR_ACCESS_KEY'
secret_key = 'YOUR_SECRET_KEY'

@private_v2_api = MaxExchangeApi::PrivateV2Api.new(access_key, secret_key)

User

GET /api/v2/members/profile

get personal profile information

@private_v2_api.member_profile

GET /api/v2/members/me

get your profile and accounts information

@private_v2_api.me

GET /api/v2/members/vip_level

get VIP level info

@private_v2_api.vip_level

Account

GET /api/v2/members/accounts

get personal accounts information

@private_v2_api.accounts

GET /api/v2/members/accounts/path_currency

get personal accounts information of a currency

@private_v2_api.account(currnecy)

Order

GET /api/v2/orders

get your orders, results is paginated.

# use default parameters
@private_v2_api.orders('maxtwd')

# provide all possible parameters
@api.orders(
  'maxtwd',
  state: 'done',
  order_by: 'desc',
  group_id: 12345,
  pagination: true,
  page: 3,
  limit: 15,
  offset: 5,
)

GET /api/v2/order

get a specific order.

# use max unique order id
@api.order(123456)

# use user specified order id
@api.order('MY_ORDER_123456', use_client_id: true)

POST /api/v2/orders/clear

cancel all your orders with given market and side

# use default parameters
@api.cancel_orders!

# provide all possible parameters
@api.cancel_orders!(market: 'maxtwd', side: 'sell', group_id: '123456')

POST /api/v2/order/delete

cancel an order

# use max unique order id
@api.cancel_order!(123456)

# use user specified order id
@api.cancel_order!('MY_ORDER_123456', use_client_id: true)

POST /api/v2/orders

create a sell/buy order

# use default parameters
@api.create_order!('maxtwd', 'buy', 1000, price: 7.5)

# provide all possible parameters
@api.create_order!(
  'maxtwd',
  'buy',
  1000,
  price: 7.5,
  client_oid: 'MY_ORDER_ID_12345',
  stop_price: 8,
  ord_type: 'limit',
  group_id: 12345678,
)

POST /api/v2/orders/multi/onebyone

Create multiple sell/buy orders, orders may be partially accepted, please put your orders as an array in json body.

# use default parameters
@api.create_orders!('maxtwd', [
  { side: 'buy', volume: '1000', price: '7.5' },
  { side: 'buy', volume: '1500', price: '7.2' },
])

# provide all possible parameters
@api.create_orders!('maxtwd', [
  { side: 'buy', volume: '1000', price: '7.5', client_oid: 'MY_ORDER_ID_12345', stop_price: '8', ord_type: 'limit' },
  { side: 'buy', volume: '1500', price: '7.2', client_oid: 'MY_ORDER_ID_12346', stop_price: '8', ord_type: 'limit' },
], group_id: 12345)

Trade

GET /api/v2/trades/my/of_order

get your executed trades related to a order

# use max unique order id
@private_v2_api.my_trades_of_order(123456)

# use user specified order id
@private_v2_api.my_trades_of_order('MY_ORDER_123456', use_client_id: true)

GET /api/v2/trades/my

get your executed trades, sorted in reverse creation order

# use default parameters
@private_v2_api.my_trades('btctwd')

# provide all possible parameters
@private_v2_api.my_trades(
  'maxtwd',
  timestamp: 1624705402,
  from: 68444,
  to: 69444,
  order_by: 'asc',
  pagination: true,
  page: 3,
  limit: 15,
  offset: 5,
)

Deposit

GET /api/v2/deposits

get your deposits history

# use default parameters
@private_v2_api.deposits('max')

# provide all possible parameters
@private_v2_api.deposits(
  'max',
  'confirmed',
  from: 68444,
  to: 69444,
  state: 'accepted',
  pagination: true,
  page: 3,
  limit: 15,
  offset: 5,
)

GET /api/v2/deposit

get details of a specific deposit

@private_v2_api.deposit('transaction_id')

GET /api/v2/deposit_addresses

The addresses could be empty before generated, please call POST /deposit_addresses in that case

# use default parameters
@private_v2_api.deposit_addresses

# provide all possible parameters
@private_v2_api.deposit_addresses(currency: 'twd', pagination: true, page: 3, limit: 15, offset: 5)

POST /api/v2/deposit_addresses

Address creation is asynchronous, please call GET /deposit_addresses later to get generated addresses

@private_v2_api.create_deposit_addresses!('twd')

Withdrawal

GET /api/v2/withdrawals

get your external withdrawals history

# use default parameters
@private_v2_api.withdrawals('max')

# provide all possible parameters
@private_v2_api.withdrawals(
  'max',
  'confirmed',
  from: 68444,
  to: 69444,
  state: 'confirmed',
  pagination: true,
  page: 3,
  limit: 15,
  offset: 5,
)

GET /api/v2/withdrawal

get details of a specific external withdraw

@private_v2_api.withdrawal('withdraw_id')

POST /api/v2/withdrawal

submit a withdrawal. IP whitelist for api token is required.

@private_v2_api.create_withdrawal!('twd', 'withdraw_address_id', 100000)

GET /api/v2/withdraw_addresses

get withdraw addresses

# use default parameters
@private_v2_api.withdraw_addresses('twd')

# provide all possible parameters
@private_v2_api.withdraw_addresses('usdt', pagination: true, page: 3, limit: 15, offset: 5)

Internal Transfer

GET /api/v2/internal_transfers

get internal transfers history

# use default parameters
@private_v2_api.internal_transfers

# provide all possible parameters
@private_v2_api.internal_transfers(
  currency: 'btc',
  side: 'in',
  from: 68444,
  to: 69444,
  pagination: true, 
  page: 3, 
  limit: 15, 
  offset: 5,
)

GET /api/v2/internal_transfer

get details of a specific internal transfer

@private_v2_api.internal_transfer('internal_transfer_id')

Reward

GET /api/v2/rewards

get rewards history

# use default parameters
@private_v2_api.rewards

# provide all possible parameters
@private_v2_api.rewards(
  currency: 'btc',
  from: 68444,
  to: 69444,
  pagination: true,
  page: 3,
  limit: 15,
  offset: 5,
)

GET /api/v2/rewards/path_reward_type

get specific rewards history

# use default parameters
@private_v2_api.rewards(reward_type: 'airdrop_rewards')

# provide all possible parameters
@private_v2_api.rewards(
  reward_type: 'airdrop_rewards',
  currency: 'btc',
  from: 68444,
  to: 69444,
  pagination: true,
  page: 3,
  limit: 15,
  offset: 5,
)

GET /api/v2/max_rewards/yesterday

get max rewards yesterday

@private_v2_api.max_rewards_yesterday

GET /api/v2/yields

get yields history

# use default parameters
@private_v2_api.yields

# provide all possible parameters
@private_v2_api.yields(
  currency: 'usdt',
  from: 68444,
  to: 69444,
  pagination: true,
  page: 3,
  limit: 15,
  offset: 5,
)

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/khiav223577/max_exchange_api. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.