> For the complete documentation index, see [llms.txt](https://xpansionchain-1.gitbook.io/xpansionchain/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://xpansionchain-1.gitbook.io/xpansionchain/products/passport/enable-user-wallet-interactions/imx-provider.md).

# IMX Provider

## IMX Provider

A provider is an interface for abstracting the user's wallet implementation from the application, which enables the development of wallet-agnostic applications.

For the XpansionChain StarkEx network, XpansionChain has defined a Provider interface incorporating the IMX-specific signable actions, such as creating an order, withdrawals, and more.

The following list details all the signable actions supported by the IMX Provider along with definitions of the request and response payloads.

### IMXProvider Methods[​](https://docs.x.immutable.com/docs/x/passport/imx-provider#imxprovider-methods) <a href="#imxprovider-methods" id="imxprovider-methods"></a>

* <mark style="color:blue;">batchNftTransfer</mark>
* <mark style="color:blue;">cancelOrder</mark>
* <mark style="color:blue;">completeWithdrawal</mark>
* <mark style="color:blue;">createOrder</mark>
* <mark style="color:blue;">createTrade</mark>
* <mark style="color:blue;">deposit</mark>
* <mark style="color:blue;">exchangeTransfer</mark>
* <mark style="color:blue;">getAddress</mark>
* <mark style="color:blue;">isRegisteredOnchain</mark>
* <mark style="color:blue;">prepareWithdrawal</mark>
* <mark style="color:blue;">registerOffchain</mark>
* <mark style="color:blue;">transfer</mark>

### Method Details[​](https://docs.x.immutable.com/docs/x/passport/imx-provider#method-details) <a href="#method-details" id="method-details"></a>

#### batchNftTransfer[​](https://docs.x.immutable.com/docs/x/passport/imx-provider#batchnfttransfer) <a href="#batchnfttransfer" id="batchnfttransfer"></a>

▸ **batchNftTransfer**(`request`): `Promise`<<mark style="color:blue;">`CreateTransferResponse`</mark>>

Create a batch of NFT transfer requests

**Parameters**[**​**](https://docs.x.immutable.com/docs/x/passport/imx-provider#parameters)

| Name      | Type                                                    | Description                      |
| --------- | ------------------------------------------------------- | -------------------------------- |
| `request` | <mark style="color:blue;">`NftTransferDetails[]`</mark> | An array of NFT transfer details |

**Returns**[**​**](https://docs.x.immutable.com/docs/x/passport/imx-provider#returns)

`Promise`<<mark style="color:blue;">`CreateTransferResponse`</mark>>

Resolves a promise that resolves with the list of Transfer IDs

**Defined in**[**​**](https://docs.x.immutable.com/docs/x/passport/imx-provider#defined-in)

<mark style="color:blue;">src/modules/provider/imxProvider.ts:73</mark>

***

#### cancelOrder[​](https://docs.x.immutable.com/docs/x/passport/imx-provider#cancelorder) <a href="#cancelorder" id="cancelorder"></a>

▸ **cancelOrder**(`request`): `Promise`<<mark style="color:blue;">`CancelOrderResponse`</mark>>

Cancel an Order

**Parameters**[**​**](https://docs.x.immutable.com/docs/x/passport/imx-provider#parameters-1)

| Name      | Type                                                             | Description                       |
| --------- | ---------------------------------------------------------------- | --------------------------------- |
| `request` | <mark style="color:blue;">`GetSignableCancelOrderRequest`</mark> | The signable cancel order request |

**Returns**[**​**](https://docs.x.immutable.com/docs/x/passport/imx-provider#returns-1)

`Promise`<<mark style="color:blue;">`CancelOrderResponse`</mark>>

Returns a promise that resolves with the cancelled Order

**Defined in**[**​**](https://docs.x.immutable.com/docs/x/passport/imx-provider#defined-in-1)

<mark style="color:blue;">src/modules/provider/imxProvider.ts:52</mark>

***

#### completeWithdrawal[​](https://docs.x.immutable.com/docs/x/passport/imx-provider#completewithdrawal) <a href="#completewithdrawal" id="completewithdrawal"></a>

▸ **completeWithdrawal**(`starkPublicKey`, `token`): `Promise`<`TransactionResponse`>

Completes a Withdrawal

**Parameters**[**​**](https://docs.x.immutable.com/docs/x/passport/imx-provider#parameters-2)

| Name             | Type                                        | Description           |
| ---------------- | ------------------------------------------- | --------------------- |
| `starkPublicKey` | `string`                                    | The stark public key  |
| `token`          | <mark style="color:blue;">`AnyToken`</mark> | The token to withdraw |

**Returns**[**​**](https://docs.x.immutable.com/docs/x/passport/imx-provider#returns-2)

`Promise`<`TransactionResponse`>

Returns a promise that resolves with the transaction

**Defined in**[**​**](https://docs.x.immutable.com/docs/x/passport/imx-provider#defined-in-2)

<mark style="color:blue;">src/modules/provider/imxProvider.ts:102</mark>

***

#### createOrder[​](https://docs.x.immutable.com/docs/x/passport/imx-provider#createorder) <a href="#createorder" id="createorder"></a>

▸ **createOrder**(`request`): `Promise`<<mark style="color:blue;">`CreateOrderResponse`</mark>>

Create an Order

**Parameters**[**​**](https://docs.x.immutable.com/docs/x/passport/imx-provider#parameters-3)

| Name      | Type                                                    | Description                                   |
| --------- | ------------------------------------------------------- | --------------------------------------------- |
| `request` | <mark style="color:blue;">`UnsignedOrderRequest`</mark> | The unsigned order request to create an order |

**Returns**[**​**](https://docs.x.immutable.com/docs/x/passport/imx-provider#returns-3)

`Promise`<<mark style="color:blue;">`CreateOrderResponse`</mark>>

Returns a promise that resolves with the created Order

**Defined in**[**​**](https://docs.x.immutable.com/docs/x/passport/imx-provider#defined-in-3)

<mark style="color:blue;">src/modules/provider/imxProvider.ts:45</mark>

***

#### createTrade[​](https://docs.x.immutable.com/docs/x/passport/imx-provider#createtrade) <a href="#createtrade" id="createtrade"></a>

▸ **createTrade**(`request`): `Promise`<<mark style="color:blue;">`CreateTradeResponse`</mark>>

Create a Trade

**Parameters**[**​**](https://docs.x.immutable.com/docs/x/passport/imx-provider#parameters-4)

<table><thead><tr><th width="179.33333333333331">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>request</code></td><td><mark style="color:blue;"><code>GetSignableTradeRequest</code></mark></td><td>The signable trade request</td></tr></tbody></table>

**Returns**[**​**](https://docs.x.immutable.com/docs/x/passport/imx-provider#returns-4)

`Promise`<<mark style="color:blue;">`CreateTradeResponse`</mark>>

Returns a promise that resolves with the created Trade

**Defined in**[**​**](https://docs.x.immutable.com/docs/x/passport/imx-provider#defined-in-4)

<mark style="color:blue;">src/modules/provider/imxProvider.ts:59</mark>

***

#### deposit[​](https://docs.x.immutable.com/docs/x/passport/imx-provider#deposit) <a href="#deposit" id="deposit"></a>

▸ **deposit**(`deposit`): `Promise`<`TransactionResponse`>

Deposit either ETH, ERC20 or ERC721 tokens

**Parameters**[**​**](https://docs.x.immutable.com/docs/x/passport/imx-provider#parameters-5)

| Name      | Type                                           |
| --------- | ---------------------------------------------- |
| `deposit` | <mark style="color:blue;">`TokenAmount`</mark> |

**Returns**[**​**](https://docs.x.immutable.com/docs/x/passport/imx-provider#returns-5)

`Promise`<`TransactionResponse`>

Returns a promise that resolves with the transaction

**Defined in**[**​**](https://docs.x.immutable.com/docs/x/passport/imx-provider#defined-in-5)

<mark style="color:blue;">src/modules/provider/imxProvider.ts:87</mark>

***

#### exchangeTransfer[​](https://docs.x.immutable.com/docs/x/passport/imx-provider#exchangetransfer) <a href="#exchangetransfer" id="exchangetransfer"></a>

▸ **exchangeTransfer**(`request`): `Promise`<<mark style="color:blue;">`CreateTransferResponseV1`</mark>>

Create a new Exchange transaction

**Parameters**[**​**](https://docs.x.immutable.com/docs/x/passport/imx-provider#parameters-6)

| Name      | Type                                                               | Description                            |
| --------- | ------------------------------------------------------------------ | -------------------------------------- |
| `request` | <mark style="color:blue;">`UnsignedExchangeTransferRequest`</mark> | The unsigned exchange transfer request |

**Returns**[**​**](https://docs.x.immutable.com/docs/x/passport/imx-provider#returns-6)

`Promise`<<mark style="color:blue;">`CreateTransferResponseV1`</mark>>

Returns a promise that resolves with the created Exchange Transaction

**Defined in**[**​**](https://docs.x.immutable.com/docs/x/passport/imx-provider#defined-in-6)

<mark style="color:blue;">src/modules/provider/imxProvider.ts:80</mark>

***

#### getAddress[​](https://docs.x.immutable.com/docs/x/passport/imx-provider#getaddress) <a href="#getaddress" id="getaddress"></a>

▸ **getAddress**(): `Promise`<`string`>

Get the Signer address

**Returns**[**​**](https://docs.x.immutable.com/docs/x/passport/imx-provider#returns-7)

`Promise`<`string`>

Returns a promise that resolves with the signer's address

**Defined in**[**​**](https://docs.x.immutable.com/docs/x/passport/imx-provider#defined-in-7)

<mark style="color:blue;">src/modules/provider/imxProvider.ts:26</mark>

***

#### isRegisteredOnchain[​](https://docs.x.immutable.com/docs/x/passport/imx-provider#isregisteredonchain) <a href="#isregisteredonchain" id="isregisteredonchain"></a>

▸ **isRegisteredOnchain**(): `Promise`<`boolean`>

Checks if a User is registered on-chain

**Returns**[**​**](https://docs.x.immutable.com/docs/x/passport/imx-provider#returns-8)

`Promise`<`boolean`>

Returns a promise that resolves with true if the User is registered, false otherwise

**Defined in**[**​**](https://docs.x.immutable.com/docs/x/passport/imx-provider#defined-in-8)

<mark style="color:blue;">src/modules/provider/imxProvider.ts:38</mark>

***

#### prepareWithdrawal[​](https://docs.x.immutable.com/docs/x/passport/imx-provider#preparewithdrawal) <a href="#preparewithdrawal" id="preparewithdrawal"></a>

▸ **prepareWithdrawal**(`request`): `Promise`<<mark style="color:blue;">`CreateWithdrawalResponse`</mark>>

Create a Withdrawal

**Parameters**[**​**](https://docs.x.immutable.com/docs/x/passport/imx-provider#parameters-7)

| Name      | Type                                           | Description                                     |
| --------- | ---------------------------------------------- | ----------------------------------------------- |
| `request` | <mark style="color:blue;">`TokenAmount`</mark> | The token type amount in its corresponding unit |

**Returns**[**​**](https://docs.x.immutable.com/docs/x/passport/imx-provider#returns-9)

`Promise`<<mark style="color:blue;">`CreateWithdrawalResponse`</mark>>

Returns a promise that resolves with the created Withdrawal

**Defined in**[**​**](https://docs.x.immutable.com/docs/x/passport/imx-provider#defined-in-9)

<mark style="color:blue;">src/modules/provider/imxProvider.ts:94</mark>

***

#### registerOffchain[​](https://docs.x.immutable.com/docs/x/passport/imx-provider#registeroffchain) <a href="#registeroffchain" id="registeroffchain"></a>

▸ **registerOffchain**(): `Promise`<<mark style="color:blue;">`RegisterUserResponse`</mark>>

Register a User to XpansionChain if they are not already registered

**Returns**[**​**](https://docs.x.immutable.com/docs/x/passport/imx-provider#returns-10)

`Promise`<<mark style="color:blue;">`RegisterUserResponse`</mark>>

Returns a promise that resolves with the user registration response

**Defined in**[**​**](https://docs.x.immutable.com/docs/x/passport/imx-provider#defined-in-10)

<mark style="color:blue;">src/modules/provider/imxProvider.ts:32</mark>

***

#### transfer[​](https://docs.x.immutable.com/docs/x/passport/imx-provider#transfer) <a href="#transfer" id="transfer"></a>

▸ **transfer**(`request`): `Promise`<<mark style="color:blue;">`CreateTransferResponseV1`</mark>>

Create a new Transfer request

**Parameters**[**​**](https://docs.x.immutable.com/docs/x/passport/imx-provider#parameters-8)

<table><thead><tr><th width="167.33333333333331">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>request</code></td><td><mark style="color:blue;"><code>UnsignedTransferRequest</code></mark></td><td>The unsigned transfer request</td></tr></tbody></table>

**Returns**[**​**](https://docs.x.immutable.com/docs/x/passport/imx-provider#returns-11)

`Promise`<<mark style="color:blue;">`CreateTransferResponseV1`</mark>>

Returns a promise that resolves with the created Transfer

**Defined in**[**​**](https://docs.x.immutable.com/docs/x/passport/imx-provider#defined-in-11)

<mark style="color:blue;">src/modules/provider/imxProvider.ts:66</mark>

***

### Types[​](https://docs.x.immutable.com/docs/x/passport/imx-provider#types) <a href="#types" id="types"></a>

#### AnyToken[​](https://docs.x.immutable.com/docs/x/passport/imx-provider#anytoken) <a href="#anytoken" id="anytoken"></a>

| Name    | Type                                        | Description               |
| ------- | ------------------------------------------- | ------------------------- |
| `token` | `ETHToken` \| `ERC721Token` \| `ERC20Token` | ID of the cancelled order |

#### EthToken[​](https://docs.x.immutable.com/docs/x/passport/imx-provider#ethtoken) <a href="#ethtoken" id="ethtoken"></a>

An ETH token

| Name   | Type    | Description              |
| ------ | ------- | ------------------------ |
| `Type` | `"ETH"` | The string literal "ETH" |

#### ERC721Token[​](https://docs.x.immutable.com/docs/x/passport/imx-provider#erc721token) <a href="#erc721token" id="erc721token"></a>

An ERC721 token

| Name           | Type       | Description                 |
| -------------- | ---------- | --------------------------- |
| `tokenAddress` | `string`   | The token address           |
| `tokenId`      | `string`   | The token ID                |
| `type`         | `"ERC721"` | The string literal "ERC721" |

#### ERC20Token[​](https://docs.x.immutable.com/docs/x/passport/imx-provider#erc20token) <a href="#erc20token" id="erc20token"></a>

An ERC20 token

| Name           | Type      | Description                |
| -------------- | --------- | -------------------------- |
| `tokenAddress` | `string`  | The token address          |
| `Type`         | `"ERC20"` | The string literal "ERC20" |

#### TokenAmount[​](https://docs.x.immutable.com/docs/x/passport/imx-provider#tokenamount) <a href="#tokenamount" id="tokenamount"></a>

| Name          | Type                                        | Description                                       |
| ------------- | ------------------------------------------- | ------------------------------------------------- |
| `TokenAmount` | `ETHToken` \| `ERC721Token` \| `ERC20Token` | Union type that represents all token type amounts |

#### ExchangeTokenAmount[​](https://docs.x.immutable.com/docs/x/passport/imx-provider#exchangetokenamount) <a href="#exchangetokenamount" id="exchangetokenamount"></a>

| Name                  | Type                       | Description                                            |
| --------------------- | -------------------------- | ------------------------------------------------------ |
| `ExchangeTokenAmount` | `ETHToken` \| `ERC20Token` | Union type that represents exchange token type amounts |

#### ETHAmount[​](https://docs.x.immutable.com/docs/x/passport/imx-provider#ethamount) <a href="#ethamount" id="ethamount"></a>

| Name     | Type     | Description                                              |
| -------- | -------- | -------------------------------------------------------- |
| `Amount` | `string` | An amount in unit Wei                                    |
| `Type`   | `ETH`    | Inherited from <mark style="color:blue;">ETHToken</mark> |

#### ERC20Amount[​](https://docs.x.immutable.com/docs/x/passport/imx-provider#erc20amount) <a href="#erc20amount" id="erc20amount"></a>

| Name           | Type     | Description                                                |
| -------------- | -------- | ---------------------------------------------------------- |
| `Amount`       | `string` | An amount in units for the given ERC20 token               |
| `Type`         | `ERC20`  | Inherited from <mark style="color:blue;">ERC20Token</mark> |
| `tokenAddress` | `string` | Inherited from <mark style="color:blue;">ERC20Token</mark> |

#### FeeEntry[​](https://docs.x.immutable.com/docs/x/passport/imx-provider#feeentry) <a href="#feeentry" id="feeentry"></a>

| Name             | Type   | Description |
| ---------------- | ------ | ----------- |
| `address`        | string | (Optional)  |
| `fee_percentage` | number |             |

### Request & Response Types[​](https://docs.x.immutable.com/docs/x/passport/imx-provider#request--response-types) <a href="#request--response-types" id="request--response-types"></a>

#### NftTransferDetails[​](https://docs.x.immutable.com/docs/x/passport/imx-provider#nfttransferdetails) <a href="#nfttransferdetails" id="nfttransferdetails"></a>

| Name           | Type   | Description                            |
| -------------- | ------ | -------------------------------------- |
| `receiver`     | string | Ethereum address of the receiving user |
| `tokenAddress` | string | The token contract address             |
| `tokenId`      | string | The token ID                           |

#### CreateTransferResponse[​](https://docs.x.immutable.com/docs/x/passport/imx-provider#createtransferresponse) <a href="#createtransferresponse" id="createtransferresponse"></a>

| Name           | Type       | Description          |
| -------------- | ---------- | -------------------- |
| `transfer_ids` | `number[]` | List of transfer IDs |

***

#### GetSignableCancelOrderRequest[​](https://docs.x.immutable.com/docs/x/passport/imx-provider#getsignablecancelorderrequest) <a href="#getsignablecancelorderrequest" id="getsignablecancelorderrequest"></a>

| Name       | Type       | Description                     |
| ---------- | ---------- | ------------------------------- |
| `order_id` | `number[]` | ID of the order to be cancelled |

***

#### CancelOrderResponse[​](https://docs.x.immutable.com/docs/x/passport/imx-provider#cancelorderresponse) <a href="#cancelorderresponse" id="cancelorderresponse"></a>

| Name       | Type       | Description               |
| ---------- | ---------- | ------------------------- |
| `order_id` | `number[]` | ID of the cancelled order |
| `status`   | `string`   | New status of the order   |

***

#### UnsignedOrderRequest[​](https://docs.x.immutable.com/docs/x/passport/imx-provider#unsignedorderrequest) <a href="#unsignedorderrequest" id="unsignedorderrequest"></a>

| Name                   | Type          | Description                                                                                 |
| ---------------------- | ------------- | ------------------------------------------------------------------------------------------- |
| `buy`                  | `TokenAmount` | The amount of tokens that will be bought for this order                                     |
| `expiration_timestamp` | `number`      | (Optional) ExpirationTimestamp in Unix time. Note: will be rounded down to the nearest hour |
| `fees`                 | `FeeEntry[]`  | (Optional) Inclusion of either maker or taker fees                                          |
| `sell`                 | `TokenAmount` | The amount of tokens that will be sold for this order                                       |

***

#### CreateOrderResponse[​](https://docs.x.immutable.com/docs/x/passport/imx-provider#createorderresponse) <a href="#createorderresponse" id="createorderresponse"></a>

| Name         | Type   | Description                                                                     |
| ------------ | ------ | ------------------------------------------------------------------------------- |
| `order_id`   | number | ID of the created order                                                         |
| `request_id` | string | (Optional) Request ID as a reference for an asynchronous order creation request |
| `status`     | string | Status of the created order                                                     |
| `time`       | number | Timestamp of the created order                                                  |

***

#### GetSignableTradeRequest[​](https://docs.x.immutable.com/docs/x/passport/imx-provider#getsignabletraderequest) <a href="#getsignabletraderequest" id="getsignabletraderequest"></a>

| Name                   | Type          | Description                                                                                 |
| ---------------------- | ------------- | ------------------------------------------------------------------------------------------- |
| `expiration_timestamp` | number        | (Optional) ExpirationTimestamp in Unix time. Note: will be rounded down to the nearest hour |
| `fees`                 | FeeEntry\[]\` | Inclusion of either maker or taker fees                                                     |
| `order_id`             | `number`      | The ID of the maker order involved                                                          |
| `user`                 | string        | Ethereum address of the submitting user                                                     |

***

#### CreateTradeResponse[​](https://docs.x.immutable.com/docs/x/passport/imx-provider#createtraderesponse) <a href="#createtraderesponse" id="createtraderesponse"></a>

| Name         | Type   | Description                                                                     |
| ------------ | ------ | ------------------------------------------------------------------------------- |
| `request_id` | string | (Optional) Request ID as a reference for an asynchronous trade creation request |
| `status`     | string | Current status of trade                                                         |
| `trade_id`   | number | ID of trade within XpansionChain                                                |

***

#### UnsignedExchangeTransferRequest[​](https://docs.x.immutable.com/docs/x/passport/imx-provider#unsignedexchangetransferrequest) <a href="#unsignedexchangetransferrequest" id="unsignedexchangetransferrequest"></a>

| Name                | Type                                                 | Description                                            |
| ------------------- | ---------------------------------------------------- | ------------------------------------------------------ |
| receiver            | string                                               | Ethereum address of the receiving user                 |
| transactionID       | string                                               | The transaction ID                                     |
| ExchangeTokenAmount | <mark style="color:blue;">ExchangeTokenAmount</mark> | Union type that represents exchange token type amounts |

***

#### UnsignedTransferRequest[​](https://docs.x.immutable.com/docs/x/passport/imx-provider#unsignedtransferrequest) <a href="#unsignedtransferrequest" id="unsignedtransferrequest"></a>

| Name          | Type                                         | Description                                       |
| ------------- | -------------------------------------------- | ------------------------------------------------- |
| `TokenAmount` | <mark style="color:blue;">TokenAmount</mark> | Union type that represents all token type amounts |
| `receiver`    | `string`                                     | New status of the order                           |

***

#### CreateTransferResponseV1[​](https://docs.x.immutable.com/docs/x/passport/imx-provider#createtransferresponsev1) <a href="#createtransferresponsev1" id="createtransferresponsev1"></a>

| Name             | Type     | Description                          |
| ---------------- | -------- | ------------------------------------ |
| `transfer_id`    | `number` | ID of the transfer                   |
| `time`           | `number` | \[deprecated] Time of the transfer   |
| `status`         | `string` | \[deprecated] The status of transfer |
| `sent_signature` | `string` | \[deprecated] Sent signature         |

***

#### CreateWithdrawalResponse[​](https://docs.x.immutable.com/docs/x/passport/imx-provider#createwithdrawalresponse) <a href="#createwithdrawalresponse" id="createwithdrawalresponse"></a>

| Name      | Type     | Description                                      |
| --------- | -------- | ------------------------------------------------ |
| `tx_hash` | `string` | XpansionChain signature authorising registration |

***

#### RegisterUserResponse[​](https://docs.x.immutable.com/docs/x/passport/imx-provider#registeruserresponse) <a href="#registeruserresponse" id="registeruserresponse"></a>

| Name      | Type     | Description                                      |
| --------- | -------- | ------------------------------------------------ |
| `tx_hash` | `string` | XpansionChain signature authorising registration |