{"id":30694301,"url":"https://github.com/goosefx1/gfx-perps-python-sdk","last_synced_at":"2025-09-02T06:05:58.882Z","repository":{"id":187836669,"uuid":"676592293","full_name":"GooseFX1/gfx-perps-python-sdk","owner":"GooseFX1","description":null,"archived":false,"fork":false,"pushed_at":"2024-06-05T05:05:39.000Z","size":176,"stargazers_count":3,"open_issues_count":2,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-08-26T17:53:27.440Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GooseFX1.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-08-09T14:52:49.000Z","updated_at":"2025-01-10T13:23:02.000Z","dependencies_parsed_at":"2023-08-12T09:56:44.537Z","dependency_job_id":"b3e0266e-840d-4fa9-b865-a82454411688","html_url":"https://github.com/GooseFX1/gfx-perps-python-sdk","commit_stats":null,"previous_names":["goosefx1/gfx-perps-python-sdk"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/GooseFX1/gfx-perps-python-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GooseFX1%2Fgfx-perps-python-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GooseFX1%2Fgfx-perps-python-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GooseFX1%2Fgfx-perps-python-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GooseFX1%2Fgfx-perps-python-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GooseFX1","download_url":"https://codeload.github.com/GooseFX1/gfx-perps-python-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GooseFX1%2Fgfx-perps-python-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273238870,"owners_count":25069797,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-02T02:00:09.530Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-02T06:05:53.768Z","updated_at":"2025-09-02T06:05:58.869Z","avatar_url":"https://github.com/GooseFX1.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"  \u003cdiv align=\"center\"\u003e\n  \u003cimg height=\"142\" src=\"https://media.goosefx.io/logos/GooseFX-light.png\" /\u003e\n  \u003ch2\u003eGooseFX Perpetual Futures SDK\u003c/h2\u003e\n\n  \u003ch4\u003e\n    \u003ca href=\"https://goosefx.io\"\u003eWebsite\u003c/a\u003e\n    \u003cspan\u003e | \u003c/span\u003e\n    \u003ca href=\"https://docs.goosefx.io\"\u003eDocs\u003c/a\u003e\n    \u003cspan\u003e | \u003c/span\u003e\n    \u003ca href=\"https://discord.com/channels/833693973687173121/833742620371058688\"\u003eDiscord\u003c/a\u003e\n    \u003cspan\u003e | \u003c/span\u003e\n    \u003ca href=\"https://www.t.me/goosefx\"\u003eTelegram\u003c/a\u003e\n    \u003cspan\u003e | \u003c/span\u003e\n    \u003ca href=\"https://medium.com/goosefx\"\u003eMedium\u003c/a\u003e\n  \u003c/h4\u003e\n  \u003cbr /\u003e\n  \u003cbr /\u003e\n\u003c/div\u003e\n\n# GooseFX Perpetual Futures SDK\n\nThis SDK contains 3 classes to interact with the GooseFX on-chain perpetual futures.\n\n- `Perp`\n- `Product`\n- `Trader`\n\nThe `Perp` class is required to initialise the connection and wallet that is going to be used for subsequent interaction.\nInitialising the `Perp` class should be the first step irrespective of the type of operation in the following manner:\n\n```python\nperp = Perp(rpc_client, 'devnet', wallet)\nperp.init()\n```\n\n### Product\n\nAn instance of the `product` class signfies one of the perp product we offer to trade. Initialization of the `product` class can be done in one of two ways:\n\n1. By index:\n\n```python\nperp = Perp(rpc_client, 'devnet', wallet)\nperp.init()\nproduct = Product(perp)\nproduct.initByIndex(0)\n```\n\n2. By name:\n\n```python\nperp = Perp(rpc_client, 'devnet', wallet)\nperp.init()\nproduct = Product(perp)\nproduct.initByName('SOL-PERP')\n```\n\nThis `product` instance will be useful for the following functions:\n\n- `GET L2 Orderbook`: Get the latest layer 2 orderbook\n\n```python\norderbook = product.get_orderbook_L2()\n```\n\n- `GET L3 Orderbook`: Get the latest layer 3 orderbook. (Orders mapped to users)\n\n```python\norderbook = product.get_orderbook_L3()\n```\n\n### Trader\n\nThe `Trader` class is required to get instructions to send transactions to the program. Each wallet must have a unique trader account initialized to be able to place orders and deposit funds. This account needs to be created once using the `create_trader_account_ixs` instruction. After it has been created once, for all subsequent interactions by the wallet, the `Trader` class needs to be initialized using the `init` function.\n\n- To create a new `Trader` account on-chain:\n\n```python\n  perp = Perp(rpc_client, 'devnet', wallet)\n  perp.init()\n  trader = Trader(perp)\n  [ixs, signers] = trader.create_trader_account_ixs()\n```\n\nwhere `ixs` is an array of required instructions and `signers` is an array of required walletairs for signature. The wallet must also sign the transaction along with the walletairs in the `signers` array\n\n- Once the account is created successfully, the `Trader` instance must be initialised in the following way:\n\n```python\n  perp = Perp(rpc_client, 'devnet', wallet)\n  perp.init()\n  trader = Trader(perp)\n  trader.init()\n```\n\n## Fractional Datatype\n\nThe Fractional data type uses a simple formula to represent a fractional number based on its mantissa (m) and exponent (exp):\n`number = mantissa / (10 ^ exponent)`\n\n## Trader Instructions\n\n### Deposit Funds\n\nTo start placing new orders, traders need to deposit some collateral. This instruction will transfer the required USDC from the wallet to the trader account which will be used as collateral to place new orders.\n\nThe only parameter to this function is the amount of USDC to be depositted.\n\n```python\n  perp = Perp(rpc_client, 'devnet', wallet)\n  perp.init()\n  trader = Trader(perp)\n  trader.init()\n  [ix, signers] = trader.deposit_funds_ix(Fractional.to_decimal(100))\n```\n\n### Withdraw Funds\n\nSimilar to deposit funds, this function takes the amount of USDC to be withdrawn as the only parameter. This instruction will transfer funds from the trader account to the wallet address.\n\n```python\n  perp = Perp(rpc_client, 'devnet', wallet)\n  perp.init()\n  trader = Trader(perp)\n  trader.init()\n  [ix, signers] = await trader.withdraw_funds_ix(Fractional.to_decimal(100))\n```\n\nNOTE: The above two instructions do not need a `product` instance as a parameter since the market is cross collateralized and the amount of USDC deposited can be used across products. The following two instructions to place a new order and cancel an order are specific to products and hence need a `product` instance as one of the parameters.\n\n### Trader's open orders for a prouct\n\nTo get all open orders for a `Trader` for a `product`:\n\n```python\n  perp = Perp(rpc_client, 'devnet', wallet)\n  perp.init()\n  product = Product(perp)\n  product.initByIndex(0)\n  trader = Trader(perp)\n  trader.init()\n  orderbookData = trader.getOpenOrders(product)\n```\n\n### New Order\n\nThe New order instruction needs the following as parameters\n\n- Quantity (Fractional)\n  **Please note: 1 unit of the product is denoted by 1 \\* 100000 units. So to buy 1 unit, the parameter to pass as quantity should be**\n\n```python\n  Fractional.to_decimal(100000)\n```\n\n- Price (Fractional)\n- Order side ('buy' or 'sell')\n- Order Type ('limit', 'market', 'immediateOrCancel', 'postOnly')\n- Product instance\n\n```python\n  perp = Perp(rpc_client, 'devnet',wallet)\n  perp.init()\n  product = Product(perp)\n  product.initByIndex(0)\n  trader = Trader(perp)\n  trader.init()\n  [ix, signers] = trader.new_order_ix(product, Fractional.to_decimal(50000), Fractional.to_decimal(35), Side.ASK, OrderType.Limit)\n```\n\n### Cancel Order\n\nThe cancel order instruction needs the orderId in string format to cancel the order. Use `getOpenOrders()` to get open orders and its id's to pass as a parameter to cancel the order\n\n```python\n  perp = Perp(rpc_client, 'devnet',wallet)\n  perp.init()\n  product = Product(perp)\n  product.initByIndex(0)\n  trader = Trader(perp)\n  trader.init()\n  [ix, signers] = trader.cancel_order_ix(product, 269375752548498747818049433352371) # Get this order id from t.get_open_orders()\n```\n\nCheckout https://github.com/GooseFX1/gfx-perps-python-sdk/blob/dev/test_perp.py for examples on the above functionalities!\n\n### Subscribe to asks\n\nThe subscribe to asks feature needs a callback function which can process added_asks which tracks the new asks at new prices and size changes which tracks if the size of ask is changed\n\n```python\n  def on_ask_change(updated_asks):\n    print(\"Updated Asks:\", updated_asks)\n\n  perp = Perp(rpc_client, 'devnet', keyp)\n  perp.init()\n  product = Product(perp)\n  product.init_by_name('SOL-PERP')\n  orderbook = product.get_orderbook_L2()\n  await product.subscribe_to_asks(on_ask_change)\n\n```\n\n### Subscribe to bids\n\nThe subscribe to bids feature needs a callback function which can process added_bids which tracks the new bids at new prices and size changes which tracks if the size of bid is changed\n\n```python\n  def on_bid_change(updated_bids):\n    print(\"Updated Bids:\", updated_bids)\n\n  perp = Perp(rpc_client, 'devnet', keyp)\n  perp.init()\n  product = Product(perp)\n  product.init_by_name('SOL-PERP')\n  orderbook = product.get_orderbook_L2()\n  await product.subscribe_to_bids(on_bid_change)\n\n```\n\nCheckout https://github.com/GooseFX1/gfx-perps-python-sdk/test_subscribe_accounts.py for examples on the subscription functionalities!\n\nHappy trading!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoosefx1%2Fgfx-perps-python-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoosefx1%2Fgfx-perps-python-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoosefx1%2Fgfx-perps-python-sdk/lists"}