Class Spot

Class for interacting with Synthetix V3 spot market contracts. Provider methods for wrapping and unwrapping assets, approvals, atomic orders, and async orders. Use get methods to fetch information about balances, allowances, and markets const { marketsById, marketsByName } = await sdk.perps.getMarkets();

Other methods prepare transactions, and submit them to your RPC. An instance of this module is available as sdk.spot. If you are using a network without spot contracts deployed, the contracts will be unavailable and the methods will raise an error. The following contracts are required:

  • SpotMarketProxy

Constructors

constructor

Properties

accountIds asyncOrderEnabled defaultAccountId? disabledMarkets marketsById marketsByName sdk

Methods

approve atomicOrder commitOrder formatSize getAllowance getBalance getMarkets getOrder getSettlementStrategies getSettlementStrategy getSynthContract initSpot resolveMarket settleOrder wrap

Constructors

constructor

Properties

accountIds

accountIds: bigint[]

asyncOrderEnabled

asyncOrderEnabled: boolean = false

OptionaldefaultAccountId

defaultAccountId?: bigint

disabledMarkets

disabledMarkets: number[] = []

marketsById

marketsById: Map<number, SpotMarketData>

marketsByName

marketsByName: Map<string, SpotMarketData>

sdk

sdk: SynthetixSdk

Methods

approve

  • approve(targetAddress, amount?, marketId?, marketName?, submit?): Promise<
        | string
        | Omit<{
            accessList: undefined;
            authorizationList: undefined;
            blobs: undefined;
            blobVersionedHashes: undefined;
            kzg: undefined;
            sidecars: undefined;
        }, "from"> & {} & {}
        | Omit<{
            accessList: undefined;
            authorizationList: undefined;
            blobs: undefined;
            blobVersionedHashes: undefined;
            kzg: undefined;
            sidecars: undefined;
        }, "from"> & {} & {}
        | Omit<{
            authorizationList: undefined;
            blobs: undefined;
            blobVersionedHashes: undefined;
            kzg: undefined;
            sidecars: undefined;
        }, "from"> & {} & {}
        | Omit<{
            authorizationList: undefined;
            blobs: undefined;
            blobVersionedHashes: undefined;
            kzg: undefined;
            sidecars: undefined;
        }, "from"> & {} & {}
        | Omit<{
            authorizationList: undefined;
            blobs: undefined;
            blobVersionedHashes: undefined;
            kzg: undefined;
            sidecars: undefined;
        }, "from"> & {} & {}
        | Omit<{
            authorizationList: undefined;
            blobs: undefined;
            blobVersionedHashes: undefined;
            kzg: undefined;
            sidecars: undefined;
        }, "from"> & {} & {}>

  • Approve an address to transfer a specified synth from the connected address. Approves the targetAddress to transfer up to the amount from your account. If amount is undefined, approves the maximum possible amount. Requires either a marketId or marketName to be provided to resolve the market.

    Parameters

    • targetAddress: string

      The address to approve.

    • Optionalamount: number

      The amount in ether to approve. Default is max uint256.

    • OptionalmarketId: number

      The ID of the market.

    • OptionalmarketName: string

      The name of the market.

    • submit: boolean = false

      Whether to broadcast the transaction.

    Returns Promise<
        | string
        | Omit<{
            accessList: undefined;
            authorizationList: undefined;
            blobs: undefined;
            blobVersionedHashes: undefined;
            kzg: undefined;
            sidecars: undefined;
        }, "from"> & {} & {}
        | Omit<{
            accessList: undefined;
            authorizationList: undefined;
            blobs: undefined;
            blobVersionedHashes: undefined;
            kzg: undefined;
            sidecars: undefined;
        }, "from"> & {} & {}
        | Omit<{
            authorizationList: undefined;
            blobs: undefined;
            blobVersionedHashes: undefined;
            kzg: undefined;
            sidecars: undefined;
        }, "from"> & {} & {}
        | Omit<{
            authorizationList: undefined;
            blobs: undefined;
            blobVersionedHashes: undefined;
            kzg: undefined;
            sidecars: undefined;
        }, "from"> & {} & {}
        | Omit<{
            authorizationList: undefined;
            blobs: undefined;
            blobVersionedHashes: undefined;
            kzg: undefined;
            sidecars: undefined;
        }, "from"> & {} & {}
        | Omit<{
            authorizationList: undefined;
            blobs: undefined;
            blobVersionedHashes: undefined;
            kzg: undefined;
            sidecars: undefined;
        }, "from"> & {} & {}>

atomicOrder

  • atomicOrder(side, size, slippageTolerance?, minAmountReceived?, marketId?, marketName?, submit?): Promise<string | CallParameters>

  • Execute an atomic order on the spot market. Atomically executes a buy or sell order for the given size. Amounts are transferred directly, no need to settle later. This function is useful for swapping sUSDC with sUSD on Base Andromeda contracts. The default slippage is set to zero, since sUSDC and sUSD can be swapped 1:1 For example: const tx = await atomicOrder(Side.BUY, 100, 0, undefined, undefined, "sUSDC"); Requires either a market_id or market_name to be provided to resolve the market.

    Parameters

    • side: Side

      The side of the order (buy/sell).

    • size: number

      The order size in ether.

    • slippageTolerance: number = 0

      The slippage tolerance for the order as a percentage (0.01 = 1%). Default is 0.

    • OptionalminAmountReceived: number

      The minimum amount to receive in ether units. This will override the slippage_tolerance.

    • OptionalmarketId: number

      The ID of the market.

    • OptionalmarketName: string

      The name of the market.

    • submit: boolean = false

      Whether to broadcast the transaction.

    Returns Promise<string | CallParameters>

commitOrder

  • commitOrder(side, size, slippageTolerance, minAmountReceived?, settlementStrategyId?, marketId?, marketName?, submit?): Promise<string | CallParameters>

  • Commit an async order to the spot market. Commits a buy or sell order of the given size. The order will be settled according to the settlement strategy. Requires either a marketId or marketName to be provided to resolve the market.

    Parameters

    • side: Side

      The side of the order (buy/sell).

    • size: number

      The order size in ether. If side is "buy", this is the amount of the synth to buy. If side is "sell", this is the amount of the synth to sell.

    • slippageTolerance: number

      The slippage tolerance for the order as a percentage (0.01 = 1%). Default is 0.

    • OptionalminAmountReceived: number

      The minimum amount to receive in ether units. This will override the slippage_tolerance.

    • settlementStrategyId: number = 0

      The settlement strategy ID. Default 2.

    • OptionalmarketId: number

      The ID of the market.

    • OptionalmarketName: string

      The name of the market.

    • submit: boolean = false

      Whether to broadcast the transaction.

    Returns Promise<string | CallParameters>

formatSize

  • formatSize(size, marketId): bigint

  • Format the size of a synth for an order. This is used for synths whose base asset does not use 18 decimals. For example, USDC uses 6 decimals, so we need to handle size differently from other assets.

    Parameters

    • size: number

      The size as an ether value (e.g. 100).

    • marketId: number

      The id of the market.

    Returns bigint

    The formatted size in wei. (e.g. 100 = 100000000000000000000)

getAllowance

  • getAllowance(targetAddress, address?, marketId?, marketName?): Promise<number>

  • Get the allowance for a target_address to transfer from address. Provide either a marketId or marketName to choose the synth.

    Parameters

    • targetAddress: string

      The address for which to check allowance.

    • Optionaladdress: string

      The owner address to check allowance for.

    • OptionalmarketId: number

      The id of the market.

    • OptionalmarketName: string

      The name of the market.

    Returns Promise<number>

    The allowance in ether.

getBalance

  • getBalance(address?, marketId?, marketName?): Promise<number>

  • Get the balance of a spot synth. Provide either a marketId or marketName to choose the synth.

    Parameters

    • Optionaladdress: string

      The address to check the balance of. If not provided, the current account will be used.

    • OptionalmarketId: number

      The id of the market.

    • OptionalmarketName: string

      The name of the market.

    Returns Promise<number>

    The balance of the synth in ether.

getMarkets

  • getMarkets(): Promise<{
        marketsById: Map<number, SpotMarketData>;
        marketsByName: Map<string, SpotMarketData>;
    }>

  • Fetches contracts and metadata about all spot markets on the network. This includes the market id, synth name, contract address, and the underlying synth contract. Each synth is an ERC20 token, so these contracts can be used for transfers and allowances. The metadata is also used to simplify interactions in the SDK by mapping market ids and names to their metadata For example: sdk.spot.wrap(100, market_name='sUSDC', submit=True) This will look up the market id for the sUSDC market and use that to wrap 100 USDC into sUSDC. The market metadata is returned from the method as a mapping object of two dictionaries/records. The first is keyed by marketsById and the second is keyed by marketsByName For example: sdk.spot.marketsByName Response: { 'sUSD' => { marketId: 0, marketName: 'sUSD', contractAddress: '0x682f0d17feDC62b2a0B91f8992243Bf44cAfeaaE' },

    Example: sdk.spot.marketsById Response: { 0 => { marketId: 0, marketName: 'sUSD', contractAddress: '0x682f0d17feDC62b2a0B91f8992243Bf44cAfeaaE' },...

    Returns Promise<{
        marketsById: Map<number, SpotMarketData>;
        marketsByName: Map<string, SpotMarketData>;
    }>

getOrder

  • getOrder(asyncOrderId, marketId?, marketName?, fetchSettlementStrategy?): Promise<SpotOrder>

  • Get details about an async order by its ID. Retrieves order details like owner, amount escrowed, settlement strategy, etc. Can also fetch the full settlement strategy parameters if fetchSettlementStrategy is true. Requires either a market_id or market_name to be provided to resolve the market.

    Parameters

    • asyncOrderId: number

      The ID of the async order to retrieve.

    • OptionalmarketId: number

      The ID of the market.

    • OptionalmarketName: string

      The name of the market.

    • fetchSettlementStrategy: boolean = true

      Whether to fetch the full settlement strategy parameters. Default is true.

    Returns Promise<SpotOrder>

    The order details.

getSettlementStrategies

  • getSettlementStrategies(stragegyId, marketIds): Promise<SpotSettlementStrategy[]>

  • Fetch the settlement strategies for all spot markets.

    Parameters

    • stragegyId: number

      The id of the settlement strategy to retrieve.

    • marketIds: number[]

      Array of marketIds to fetch settlement strategy

    Returns Promise<SpotSettlementStrategy[]>

    Settlement strategy array for markets

getSettlementStrategy

  • getSettlementStrategy(settlementStrategyId, marketId?, marketName?): Promise<SpotSettlementStrategy>

  • Fetch the settlement strategy for a spot market.

    Parameters

    • settlementStrategyId: number

      The id of the settlement strategy to retrieve.

    • marketId: undefined | number = undefined

      The id of the market.

    • marketName: undefined | string = undefined

      The name of the market.

    Returns Promise<SpotSettlementStrategy>

getSynthContract

  • getSynthContract(marketId?, marketName?): {}

  • Fetch the underlying synth contract for a market. Synths are represented as an ERC20 token, so this is useful to do things like check allowances or transfer tokens. This method requires a marketId or marketName to be provided.

    Parameters

    • OptionalmarketId: number

      The id of the market.

    • OptionalmarketName: string

      The name of the market

    Returns {}

    initSpot

    resolveMarket

    • resolveMarket(marketId?, marketName?): {
          resolvedMarketId: number;
          resolvedMarketName: string;
      }

    • Look up the market_id and market_name for a market. If only one is provided, the other is resolved. If both are provided, they are checked for consistency.

      Parameters

      • marketId: undefined | number = undefined

        Id of the market to resolve

      • marketName: undefined | string = undefined

        Name of the market to resolve

      Returns {
          resolvedMarketId: number;
          resolvedMarketName: string;
      }

      • resolvedMarketId: number
      • resolvedMarketName: string

    settleOrder

    • settleOrder(asyncOrderId, marketId?, marketName?, maxTxTries?, txDelay?, submit?): Promise<undefined | string | CallParameters>

    • Settle an async Pyth order after price data is available. Fetches the price for the order from Pyth and settles the order. Retries up to maxTxTries times on failure with a delay of txDelay seconds. Requires either a marketId or marketName to be provided to resolve the market.

      Parameters

      • asyncOrderId: number

        The ID of the async order to settle.

      • OptionalmarketId: number

        The ID of the market

      • OptionalmarketName: string

        The name of the market.

      • maxTxTries: number = 5

        Max retry attempts if price fetch fails.

      • txDelay: number = 2

        Seconds to wait between retries.

      • submit: boolean = false

        Whether to broadcast the transaction.

      Returns Promise<undefined | string | CallParameters>

    wrap

    • wrap(size, marketId?, marketName?, submit?): Promise<string | CallParameters>

    • Wrap an underlying asset into a synth or unwrap back to the asset. Wraps an asset into a synth if size > 0, unwraps if size < 0. The default slippage is set to zero, since the synth and asset can be swapped 1:1. For example: const tx = wrap(100, undefined, "sUSDC") # wrap 100 USDC into sUSDC const tx = wrap(-100, undefined, "sUSDC") # unwrap 100 sUSDC into USDC Requires either a market_id or market_name to be provided to resolve the market.

      Parameters

      • size: number

        The amount of the asset to wrap/unwrap.

      • OptionalmarketId: number

        The ID of the market.

      • OptionalmarketName: string

        The name of the market.

      • submit: boolean = false

        Whether to broadcast the transaction.

      Returns Promise<string | CallParameters>

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Methods