Comment on page
Typescript SDK
GooseFX Perpetual Futures SDK is designed for market makers and trading enthusiasts, allowing interaction with the GooseFX on-chain perpetual futures.
The Typescript SDK consists of three classes:
- 1.Perp
- 2.Product
- 3.Trader
The Perp class is essential for initializing the connection and wallet used for subsequent interactions. Initializing the Perp class should always be the first step, regardless of the operation type. Here's an example of how to initialize the Perp class.
const perp = new Perp(connection, 'mainnet', wallet);
await perp.init();
A Product instance represents one of the perpetual products we offer to trade. You can initialize the Product class in two ways: by index or by name. The Product instance can be used for various functions, such as getting the L2 and L3 orderbooks, and subscribing to the orderbook.
const perp = new Perp(connection, 'mainnet', wallet);
await perp.init();
const product = new Product(perp);
product.initByIndex(0);
const perp = new Perp(connection, 'mainnet', wallet);
await perp.init();
const product = new Product(perp);
product.initByName('SOL-PERP');
1. Get L2 Orderbook
const orderbook = await product.getOrderbookL2();
2. Get L3 Orderbook
const orderbook = await product.getOrderbookL3();
3. Subscribe to Orderbook
Subscribe to the orderbook account and listen to changes. Pass your function as the parameter to the
subscribeToOrderbook
function to handle orderbook changes. Don't forget to unsubscribe when it's no longer needed!async function handleAccountChange(){
const res = await product.getOrderbookL2();
console.log("Updated orderbook: ", res);
}
const subscribeId = product.subscribeToOrderbook(handleAccountChange);
connection.removeAccountChangeListener(subscribeId); //To close the subscription
Trader
The Trader class is necessary for obtaining instructions to send transactions to the program. Each wallet must have a unique trader account initialized to place orders and deposit funds. Create the trader account once using the
createTraderAccountIxs
instruction. After that, initialize the Trader class using the init
function for all subsequent wallet interactions. const perp = new Perp(connection, 'mainnet', wallet);
await perp.init();
const trader = new Trader(perp);
const [ixs, signers] = await trader.createTraderAccountIxs();
In this example,
ixs
is an array of required instructions and signers
is an array of required keypairs for signature. The wallet must also sign the transaction along with the keypairs in the signers
array.Once you successfully create an account, initialize the Trader instance as follows:
The Fractional data type represents a fractional number based on its mantissa (m) and exponent (exp) using this formula:
number = mantissa / (10 ^ exponent)
.To place new orders, traders need to deposit collateral. This instruction transfers the required USDC from the wallet to the trader account, which will be used as collateral to place new orders.
The only parameter for this function is the amount of USDC to deposit:
const perp = new Perp(connection, 'mainnet', wallet);
await perp.init();
const trader = new Trader(perp);
await trader.init();
const ix = await trader.depositFundsIx(new Fractional({
m: new BN(1),
exp: new BN(0)
}));
Similar to depositing funds, this function takes the amount of USDC to be withdrawn as the only parameter. This instruction transfers funds from the trader account to the wallet address:
const perp = new Perp(connection, 'mainnet', wallet);
await perp.init();
const trader = new Trader(perp);
await trader.init();
const ix = await trader.withdrawFundsIx(new Fractional({
m: new BN(1),
exp: new BN(0)
}));java
Note: The deposit and withdraw instructions do not require a
product
instance as a parameter, as the market is cross collateralized and the amount of USDC deposited can be used across products. The following instructions, placing a new order and canceling an order, are specific to products and need a product
instance as one of the parameters.To get all open orders for a
Trader
for a product
: const perp = new Perp(connection, 'mainnet', wallet);
await perp.init();
const product = new Product(perp);
product.initByIndex(0);
const trader = new Trader(perp);
await trader.init();
const orderbookData = await trader.getOpenOrders(product);
console.log("orderbook: ", orderbookData);
The new order instruction requires the following parameters:
- Quantity (Fractional): 1 unit of the product is denoted by 1 * 100,000 units. To buy 1 unit, pass the following parameter as quantity:
new Fractional({
m: new BN(100000),
exp: new BN(0)
})
- Price (Fractional)
- Order side ('buy' or 'sell')
- Order Type ('limit', 'market', 'immediateOrCancel', 'postOnly')
- Product instance
Here's an example of placing a new order:
const perp = new Perp(connection, "mainnet", wallet);
await perp.init();
const product = new Product(perp);
product.initByIndex(0);
const trader = new Trader(perp);
await trader.init();
const ix = await trader.newOrderIx(
new Fractional({
m: new BN(10000), //Implies 0.1 units
exp: new BN(0),
}),
new Fractional({
m: new BN(2245), //Price 22.45$
exp: new BN(2),
}),
"buy",
"limit",
product
);
The cancel order instruction requires the
orderId
in string format. Use getOpenOrders()
to get open orders and their IDs to pass as a parameter to cancel the order:const perp = new Perp(connection, "mainnet", wallet);
await perp.init();
const product = new Product(perp);
product.initByIndex(0);
const trader = new Trader(perp);
await trader.init();
const ix = await trader.cancelOrderIx("7922816251444880503428103912726", product);
Checkout https://github.com/GooseFX1/gfx-perp-ts-sdk/blob/main/test/index.test.js for examples on the above functionalities!
Last modified 2mo ago