API Reference
These docs are for v2.0. Click to read the latest docs for v2.0.1.

Deposit & Withdraw Funds

The Margin Bank smart contract is responsible for storing all funds deposited by users into the exchange.

Funds being used to collateralize positions are removed from a users Margin Bank balance and consequently unavailable to be withdrawn. Once the position is closed, these funds flow back to the user's balance after accounting for the position's profit or loss.

Funds being used to collateralize open orders off-chain are kept in the users Margin Bank balance. Consequently these funds are available to be withdrawn; however, if a user withdraws funds being used to collateralize open orders, the associated open orders will be cancelled.

Below is an example of how to deposit and withdraw funds from Margin Bank

/**
  * Example of deposit and withdrawal from Bluefin MarginBank
 */

/* eslint-disable no-console */
import { Networks, BluefinClient } from "@bluefin-exchange/bluefin-v2-client";

async function main() {
  // ensure that account has enough native gas tokens to perform on-chain contract call
  const dummyAccountKey =
    "trigger swim reunion gate hen black real deer light nature trial dust";

  // using TESTNET network, getUSDCBalance does not work on MAINNET
  const client = new BluefinClient(
    true,
    Networks.TESTNET_SUI,
    dummyAccountKey,
    "ED25519" //valid values are ED25519 or Secp256k1
  ); //passing isTermAccepted = true for compliance and authorizarion
  await client.init();
  console.log(await client.getPublicAddress());

  // deposits 10 USDC to margin bank, uses default USDC/MarginBank Contracts
  // assuming user has 1 USDC locked in margin bank, else will throw
  console.log(
    "USDC Deposited to MarginBank: ",
    await client.depositToMarginBank(10)
  );
  console.log(
    "USDC Withdrawn from MarginBank: ",
    await client.withdrawFromMarginBank(1)
  );
  console.log("Current balance", await client.getUSDCBalance());
}

main().then().catch(console.warn);


from bluefin_v2_client import BluefinClient, Networks
import asyncio


async def main():
	ed25519_wallet_seed_phrase =
    "person essence firm tail chapter forest return pulse dismiss unlock zebra amateur";

  client = BluefinClient(
      True, # agree to terms and conditions
      Networks["SUI_STAGING"], # network to connect i.e. SUI_STAGING or SUI_PROD
      ed25519_wallet_seed_phrase, # seed phrase of the wallet
  )

  # on boards user on bluefin. Must be set to true for firs time use
  await client.init(True)
  
  # check margin bank balance on-chain
  print("Margin bank balance:", await client.get_margin_bank_balance())

  print("USDC deposited:", await client.deposit_margin_to_bank(5000))

  # check margin bank balance
  resp = await client.get_margin_bank_balance()
  print("Margin bank balance:", resp)

  # withdraw margin bank balance
  print("USDC Withdrawn:", await client.withdraw_margin_from_bank(10))

  # check margin bank balance
  print("Margin bank balance:", await client.get_margin_bank_balance())

  print("Withdraw all", await client.withdraw_all_margin_from_bank())

  print("Margin bank balance:", await client.get_margin_bank_balance())
  await client.close_connections()


if __name__ == "__main__":
    loop = asyncio.new_event_loop()
    loop.run_until_complete(main())
    loop.close()

Deposit To Margin Bank

The Deposit To Margin Bank method allows users to deposit USDC tokens from the native USDC contract into the exchange. User funds are maintained against their account in the margin bank as available free collateral. These funds will be used to open orders and positions on the exchange.

Note, this method requires that the user has USDC funds in their wallet (on the official on-chain USDC Contract). The method takes in the following parameters:

  • Amount: The amount to be deposited to the margin bank in base format (the method will take care of converting it to big number string format supported on-chain).

If the wallet address is identified as high-risk during deposit, the user will not be able to place new orders, open new positions, or deposit funds into the exchange. They may, however, close out any open positions and withdraw their funds.

The response will have the following schema:

type ResponseSchema = {
    ok: boolean; // boolean indicating contract call success/failure
    data: any; // transaction data
    message: string; // success / error message
    code?: number | string; // status code
    stack?: string; // error stack
  };

📘

Margin Bank Balance vs Free Collateral

The Margin Bank balance does not account for open orders. Given open orders are tracked only in the off-chain orderbook, balance used to collateralize them is not yet accounted for in the on-chain balance. Withdrawing funds from the Margin Bank before cancelling open orders will result in the open orders being force cancelled.

To see the balance with accounting for off-chain orders and on-chain positions, please instead use the Free Collateral field from the GET /account route.

Withdraw Funds From Margin Bank

The Withdraw From Margin Bank method allows user to withdraw their deposited USDC from the Margin Bank contract. The contract unlocks and transfers the funds back to the on-chain USDC contract; the funds will be back in the user's wallet.

As before, please note that the Margin Bank only contains available funds and will not include any balance being used to collateralize open positions or orders. To withdraw funds locked into positions and orders, please close the open positions and cancel the open orders first.

The method takes in the following optional parameters:

  • Amount (Optional): The amount of margin to be withdrawn. The amount must be in base format (the method will take care of converting it to big number string format supported on-chain). If the amount is not passed as input, all available funds in the margin bank will be withdrawn.

The response will have the following schema:

type ResponseSchema = {
    ok: boolean; // boolean indicating contract call success/failure
    data: any; // transaction data
    message: string; // success / error message
    code?: number | string; // status code
    stack?: string; // error stack
  };