ImmutableX Javascript SDK

This repository contains everything partners need to launch the link, and make transactions on IMX. For all documentation needs, please go to docs.x.immutable.com

Note: Currently our SDK is only officially compatible with Node v18.

CHANGELOG

Index

3.8.2

Fix ERC20 withdrawals by updating retrieval of asset type from encoding API and removing decimal from payload.

3.8.1

Fix NFT withdrawals by updating generation of asset ID to use encoding API.

3.8.0

Add getStarkExContractMajorVersion to return the StarkEx contract version number.

3.7.1

Update withdrawal tests.
Simplify withdrawal V2 token logic.
Fix use of ownerKey in withdrawal V2.

3.7.0

Add support for ERC721 token type to complete withdrawal and register and complete withdrawal flows when StarkEx contract version >= 4.0.

3.6.0

Add registerAndCompleteWithdrawal to allow an unregistered user to complete withdrawal using updated exchange contract.
Add withdrawalAll to call updated exchange contract.
Update getWithdrawalBalanceV4 to use controller.getAssetId when StarkEx contract version >= 4.0.

3.5.0

Add completeWithdrawalV2F.
Update completeWithdrawalF to use completeWithdrawalV2F when StarkEx contract version >= 4.0.
Update isRegisteredStarkF to be compatible with change in behavior of getEthAddress StarkEx contract function in v4.

3.4.0

Add StarkEx V4.0 contract bindings.
Add registerEthAddress to enable use of function on StarkEx V4.0.

3.3.0

Update prepare withdrawal flow to fetch StarkEx contract version and execute logic appropriate for the version.

3.2.0

Update deposit flow to fetch StarkEx contract version and execute the deposit flow appropriate for the version.

3.1.3

Add getStarkExContractVersion to fetch the StarkEx contract version.

3.1.2

Extend order quantity_with_fees type range to include 0.

3.1.1

Fix bug where window.ethereum has multiple providers, but no setSelectedProvider function.

3.1.0

Bump Ethers version to ^5.7.1 to support Sepolia.

3.0.0

Remove functions that interface with v1 orders & trades API endpoints as v1 version of that API has been sunsetted.
Removed orderAndTradeAPIVersion parameter from the Link class constructor, this is no longer needed as order and trade API version 3 will be the only available default.

2.1.1

Added sunset date for v1 order book functions

2.1.0

Add New Ganymede as game wallet provider preference type

2.0.3

Added support to generate backwards compatible stark key using getKeyPairFromPath for accounts created with versions before 1.43.5 and also imx-core-sdk

2.0.2

fix readme.md

2.0.1

remove wallet_connect provider preference to clean up after removal
updates to readme

2.0.0

Deprecate all @walletconnect/* deps
Refactor build tooling to support Node 18 (upgrades to Rollup 3.x)
Update magic-sdk to support Node 18

For more information on migration, please see: https://docs.x.immutable.com/docs/x/node16-migration/

1.43.7

Fixed GrindKey logic to correctly generate deterministic stark key.
Provided backwards compatible way to generate starkkey after this GrindKey Fix.

1.43.6

Deprecate v1 versions of getTrade and getTrades functions.
Add v3 versions of getTrade and getTrades functions.

1.43.5

Fix readme index

1.43.4

Fix an issue when attempting a Transfer with a Link SDK created with a value for the orderAndTradeAPIVersion parameter.

1.43.3

Fix createOrderRequestV3F function implementation.
Add unit tests for v3 order & trade functions.

1.43.2

Add SDK dependency tracking.
Update critical dependencies.

1.43.1

Add Planet quest marketplace domains to experimental feature whitelist.
Remove experimental tag from bids/offers functions.

1.43.0

Add optional parameter in the Link constructor function to allow targeting v3 endpoints for order and trade flows.

1.42.1

Revert changes from 1.42.0. Problem with transpiling Web3Modal package

1.42.0

Add support for WalletConnect V2.
Added wallet_connect_v2 as a ProviderPreference

1.41.3

Add token type, token address, decimals, and symbol to Maker Taker Fees type
Add updated_timestamp to Get Order V3 result

1.41.2

Fix changelog

1.41.1

Add deprecation headers and warning logs for deprecated functions

1.41.0

Add support for the optional splitFees parameter when invoking ImmutableXClient.createOrderV3

1.40.1

Removed experimental flags on bids/offers endpoints
Introduced maker_fees and taker_fees fields to the getOrderV3 and getOrdersV3 endpoints

1.40.0

Add imx-link-info events for disptaching wallet change events on the buy route
With game wallets and their specific collections, the link.buy() route may suggest that users connect with a specific game wallet before purchasing, this will dispatch an event so that marketplaces are kept in sync with the Link connected wallet provider

1.39.1

Fix broken import in gameWalletProvider

1.39.0

Add support for Game Wallet Auto Detect feature in Link
Add Cross the Ages and KYO as game wallet provider preference types

1.38.6

Add support for taker fees to signature generation process in CreateOrderWithFeeV3

1.38.5

Add support for taker fees to CreateTradeV3

1.38.4

Add support for taker fees to Link AcceptOffer parameters

1.38.3

Add Planet quest URLs to experimental feature whitelist

1.38.2

Bugfix for dangling event handlers

1.38.1

Rename gameIcon to gameIconUrl in GameWalletProviderOptions type

1.38.0

Add game wallet provider setup to getEthereumProvider
Allow for providerPreference to be extended for game wallet providers

1.37.6

Update parameter name for primary and secondary sales: wallet_address is now user_wallet_address

1.37.5

Update typo in whitelisted domain nfttrade.com -> nftrade.com

1.37.4

Updated whitelisted domains to include tokentrove.com, okx.com and nfttrade.com

1.37.3

Updated ImmutableOrderStatus type invalid -> renamed to inactive to match API responses
Updated ImmutableFeeType type to include maker and taker

1.37.2

Updated ImmutableOrderStatus type to include invalid

1.37.1

Updated ImmutableXClient to enhance internal error handlers

1.37.0

Add fees parameter to link.makeOffer function

1.36.1

Update supported exchange types for getCurrenciesV3()

1.36.0

Add experimental getCurrenciesV3()

1.35.7

Remove experimental flag from nftCheckout and createExchangeV3 methods

1.35.6

Fix return value for getSecondaryTransactionsHistory()

1.35.5

Added method isMobile()

1.35.4

Add experimental method getSecondaryTransactionsHistory()

1.35.3

Update supported_currencies in WidgetParams
Add onramp and offramp in ImmutableExchangeType
Add provider in NFTCheckoutPrimaryParamsCodec

1.35.2

Exclude sellerWalletAddress from NFTCheckoutSecondaryParamsCodec

1.35.1

Exclude seller_wallet_address from nftCheckoutPrimary

1.35.0

Added third-party cookie blocking policy check when running Link methods on the iFrame mode to return error 1004 if third-party cookies blocked
Updated Link methods to return defined errors when rejecting asynchrounous operations
Updated Link methods to return error 1003 if the user closes Link
Updated Link methods to return error 1005 if the domain is not authorized to use the iFrame mode

1.34.0

Add experimental method for creating a buy order createOrderV3
Add experimental method for accepting a buy order createTradeV3
Add experimental method for cancelling a buy order cancelOrderV3

1.33.0

Add experimental nftCheckoutPrimary, nftCheckoutSecondary, getNFTSecondaryTransactionStatus and createExchangeV3 methods

1.32.2

Add id param to exchange signable-transfer-details

1.32.1

Fixing event listener origin path

1.32.0

Revert changes from 1.31.0

1.31.0

Updating ImmutableETHToken and ImmutableERC20Token types to include quantity_with_fees property

1.30.0

Add experimental method for acceptOffer link.acceptOffer

1.29.0

Update Ropsten config to Sandbox/Goerli.

1.28.0

Add experimental methods for makeOffer link.makeOffer and cancelOffer link.cancelOffer

1.27.0

Add experimental getPrimaryTransactions method

1.26.1

Update getEthereumProvider method to detect multiple wallet extensions properly

1.26.0

Remove syncState method

1.25.1

Update PrimaryTransactionStatus to support waitingAuthorization transaction status

1.25.0

Add experimental createNFTPrimaryTransaction and getNFTPrimaryTransactionStatus methods to create/get primary sale transaction

1.24.1

Update default webUrl in Link to https://link.ropsten.x.immutable.com

1.24.0

Update ImxClient getOrders to support buy_token_name parameter

1.23.0

Update ImxClient getOrders to support updated_min_timestamp and updated_max_timestamp parameters

1.22.3

Increment engine version to v16

1.22.1

Add MultipleExtensionsError when default ethereum was rewritten

1.22.0

Add Gamestop provider preference

1.21.4

Fix header key and value for createTradeWithRiskAssessment method to trigger risk assessment

1.21.3

Remove experimental flag for cryptoToFiat function

1.21.2

Update FiatToCrypto and CryptoToFiat result codecs

1.21.1

Add experimental duplicated create trade method with x-wallet-sdk-version header

1.21.0

Receiving Magic configuration as params of the getProvider function instead of reading it from the localStorage.

1.20.4

Update user registration request by adding email field

1.20.3

Add experimental verifyOTP method
Add experimental getAwaitingOrderStatus method

1.20.2

Add eth headers for exchange transfer endpoints

1.20.1

Fix the vulnerabilitie by bumping the dependency version

1.20.0

Add custom WalletConnect QR code modal to improve UX

1.19.0

Add new optional attribute email to the response of the method setup(), this value will be set only when connecting through Magic.

1.18.0

Updated ethBalanceV2 and erc20BalanceV2 to stop repetitively fetching the balance

1.17.0

Add L1 message signing to transactions

1.16.0

Add a new method to get public encryption key getPublicKey()

1.15.0

Add ethBalanceV2 and erc20BalanceV2 to support read balances via a provider without connect to the wallet

1.14.1

Remove experimental flag for sign()

1.14.0

Update dependency: etherjs to 5.6.0

1.13.0

Add a new experimental method sign()

1.12.0

Add new walletconnect provider
Updated getProvider to accept optional provider options

1.11.1

Add crypto-to-fiat awareness on getExchanges

1.11.0

Removed method getExchangesV1F
Removed method getExchangesV1
Removed method createExchangeV1
Removed method getExchangeV1
Removed param version on method getMoonpaySignature

1.10.2

Fix Exchange transfer to use V1 Params

1.10.1

Updated getCurrencies to return currencies list by exchange type

1.10.0

Experimental Added syncState method. link.syncState() will: 1 - add a persistant invisible iframe to the dom, and 2 - resolve with an observable, which will stream events as they come in from link, whenever the user changes their wallet, network or disconnects etc.

1.9.1

getExchange returns optional provider wallet address

1.9.0

Experimental Added getCurrencies method

1.8.3

validateCurrencyAmount returns null or number for min_amount and max_amount

1.8.2

Experimental Removed validateCurrencyAmount method
Experimental Added getCurrencyLimits method

1.8.0

Added calculation function calculateFeeBreakdownFromPriceAmounts
Updated calculateFeeBreakdownFromBasePrice to allow for protocol fees to be supplied
Updated calculateFeeBreakdownFromFullPrice to allow for protocol fees to be supplied

1.7.0

Experimental Added signableTransferDetails and createExchangeTransfer methods
Experimental Add amount parameter to cryptoToFiat
Experimental Add validateCurrencyAmount method

1.6.1

Ease CryptoCurrencies validation to allow string. Link will validate it

1.6.0

Added WALLET_CONNECT in ProviderPreference enum

1.5.0

Added calculation functions for order price and fee breakdowns
calculateFeeBreakdownFromBasePrice: specify the base price and all fees to be applied
calculateFeeBreakdownFromFullPrice: specify the price inclusive of fees and all fees applied to it

1.4.0

Experimental Added cryptoToFiat method

1.3.53

Bugfix for missing ERC20 type

1.3.52

Enable batch transfer for NFTs batchNftTransfer

1.3.51

listBalances fix bug to support multiple symbols

1.3.50

createExchange now use v2 endpoints
createExchangeV1 support the old functionality

1.3.49

Removes experimental warnings from methods involving maker/taker fees

1.3.48

Fix fee floating point precision bug for createOrder

1.3.47

getExchanges and getExchange now use v2 endpoints
getExchangesV1 and getExchangeV1 support the old functionality

1.3.46

Experimental Update types for link batch transfer

1.3.45

Add support for exchange v2 endpoints

1.3.44

Update request type for method getMoonpaySignature

1.3.43

Experimental Add more types for transfer v2 endpoint

1.3.42

Updated response type for ImmutableXClient method cancelOrder

1.3.41

Experimental Allow specifying fees to Link.cancel

1.3.40

Experimental Add transfer v2 endpoint support

1.3.39

Bugfix: fix getTrade() types
Update request and response types for experimental method getProjects
Update type for ProjectResult

1.3.38

Updated fiatToCrypto() to accept cryptoCurrencies

1.3.37

Experimental Allow specifying fees on getAssets()

1.3.36

Added pagination for the exchanges list endpoint

1.3.35

Bugfix: restore the types and funcitonality of sell_token_name inside of getOrdersF()

1.3.34

Enable order expiration date override from Link

1.3.33

Remove Experimental flag from fiatToCrypto method

1.3.32

Allow user to override the order expiration date

1.3.31

Renamed the exchange() method to fiatToCrypto()

1.3.30

Remove Experimental flag from deposit without params or without amount or token

1.3.29

Experimental Updated experimental maker/taker fees with bindings for Link

1.3.28

Update transfers to allow transfer of more than 50 assets at a time
Implemented update transfers to allow transfer of more than 50 assets at a time, not yet enabled

1.3.27

Refactoring the exchange history
Adding currency parameter for the exchange

1.3.26

Fix listTokens query param generation for symbols filter

1.3.25

Experimental Update deposit to allow to send request without amount or without any params

1.3.24

Bugfix for detecting wallet extensions

1.3.23

Handle multiple wallet extensions when getting Etherum provider

1.3.22

Experimental Updated experimental maker/taker fees feature to allow specifying fee percentages with 2 d.p. of precision.

1.3.21

Experimental Update fee param name for getOrder and getOrders

1.3.20

Experimental Added taker fees to getOrder and getOrders

1.3.19

Experimental Added taker fees to createTrade

1.3.18

Retry on throttled requests (HTTP 429) to API.

1.3.17

Remove Experimental flag from sell flow.

1.3.16

Experimental Added currency information to exchange types

1.3.15

Experimental Added functions to retrieve the exchange history by user.

1.3.14

Rename get orders parameter from buy_token_contract to buy_token_address
Experimental Updated the codec types for exchange methods.

1.3.13

Experimental Updated Magic api key.

1.3.12

Fix for ImmutableXClient; default apiUrl in axios config.

1.3.11

Added optional apiKey header to all requests to the IMX public api, for use with ratelimiting.

1.3.10

1.3.9

Experimental Bugfixes for the exchange method

1.3.8

Added optional enableDebug header to constructor of ImmutableXClient, to enable debug logging.

1.3.7

Adding providerPreference and ethNetwork to link.setup() response.
Exporting LocalStorageKeys enum with the keys used internally.

1.3.6

The getCollection and getCollections methods were updated to have new field metadata_url in the response incorrectly. This fixes the error by changing it to metadata_api_url.
Adds getMetadataSchema method
Update request/response objects for collection and metadata APIs

1.3.5

The getCollection and getCollections methods returns a new field metadata_url in the response.
Specify supported node versions (12 and 14) in package.json engines.s

1.3.4

ImmutableSellOrderCodec: update buy_decimals to be an optional and add contract_address, status as optional fields.
ImmutableBuyOrderCodec: update sell_decimals to be an optional and add contract_address, status as optional fields.

1.3.3

Experimental support for projects and collections functionality.

1.3.2

Experimental support to new exchange method.

1.3.1

Refactor internal implementation for experimental features.

1.3.0

Added missing type definition for sell param + check location.origin instead of referrer
SellParamsCodec: update amount to be an optional and add currencyAddress as an optional param as well.

1.2.8

Bugfix on mint v2 response typing

1.2.7

Update mint v2 endpoint's response schema to {token_id, contract_address, tx_id}

1.2.6

Renaming ProviderPreference options.

1.2.5

Experimental temporary testing mint v2 endpoint with response as a mapping of NFTs to tx IDs

1.2.4

Experimental support to easy login with Magic when used via Link.

1.1.6

signMessage() function added to Client
Controller's signVerifyEth() parametrized and renamed

1.1.6

Add signAuthHeader for new Authentication process

1.1.5

Claim routes added

1.1.4

Fix import recovery param for ledger signing

1.1.3

include_fees param for POST requests placed in POST body instead of in query param

1.1.2

Bug fix on createOrders

1.1.1

Add allowance and approve methods for ERC20 tokens
Remove uneccessary fields from mintv2

1.1.0

Includes royalty fees by default in the following endpoints:

link.getOrder
link.getAssets
link.getOrder
link.getAsset
link.createOrder
link.createTrade

which will include a fee body with fee information (if exists).

1.0.2

Updated responses for link methods

link.prepareWithdrawal now contains withdrawalId
link.completeWithdrawal now contains transactionId

1.0.1

SDK JS is now built with node 12 instead of node 14.

1.0.0

1.0.0 marks the first public release of @imtbl/imx-sdk. Bundled in this release, are the following features:

Transfer functionality has been refactored to support multiple transfers at once imx-docs