> 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/key-concepts/deep-dive-into-api-concepts.md).

# Deep dive into API concepts

## Deep dive into API concepts

This page provides information on how to generate the following API headers and params:

| Header / Param                                                                                                          | Used in:                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <ul><li><mark style="color:blue;">IMX-Timestamp</mark></li><li><mark style="color:blue;">IMX-Signature</mark></li></ul> | <ul><li><mark style="color:blue;">createCollection</mark></li><li><mark style="color:blue;">updateCollection</mark></li><li><mark style="color:blue;">addMetadataSchemaToCollection</mark></li><li><mark style="color:blue;">updateMetadataSchemaByName</mark></li><li><mark style="color:blue;">createProject</mark></li></ul>                                                                                                                                                                                                                                                                                                                                                                                  |
| <ul><li><mark style="color:blue;">x-imx-eth-signature</mark></li></ul>                                                  | <ul><li><mark style="color:blue;">Get a list of metadata refreshes</mark></li><li><mark style="color:blue;">Requesting a metadata refresh</mark></li><li><mark style="color:blue;">Get metadata refresh results</mark></li><li><mark style="color:blue;">Get metadata refresh errors</mark></li><li><mark style="color:blue;">createOrder</mark></li><li><mark style="color:blue;">cancelOrder</mark></li><li><mark style="color:blue;">createTransferV1</mark></li><li><mark style="color:blue;">createTransfer</mark></li><li><mark style="color:blue;">createWithdrawal</mark></li><li><mark style="color:blue;">createTrade</mark></li><li><mark style="color:blue;">createExchangeTransfer</mark></li></ul> |
| <ul><li><mark style="color:blue;">stark\_signature</mark></li></ul>                                                     | <ul><li><mark style="color:blue;">createOrder</mark></li><li><mark style="color:blue;">cancelOrder</mark></li><li><mark style="color:blue;">createTransferV1</mark></li><li><mark style="color:blue;">createTransfer</mark></li><li><mark style="color:blue;">createWithdrawal</mark></li><li><mark style="color:blue;">createTrade</mark></li><li><mark style="color:blue;">createExchangeTransfer</mark></li></ul>                                                                                                                                                                                                                                                                                             |
| <ul><li><mark style="color:blue;">auth\_signature</mark></li></ul>                                                      | <ul><li><mark style="color:blue;">mintTokens</mark></li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |

UPGRADE YOUR SDK TO AVOID GENERATING THESE HEADERS

If you are using the <mark style="color:blue;">Core SDK</mark> or the <mark style="color:blue;">JS SDK</mark>, you will generally not need to provide these headers as long as you upgrade to the following versions:

* Core SDK: `>= 1.0.0-beta.2`
* JS SDK: `>= 1.17`

### `IMX-Timestamp` (string)[​](https://docs.x.immutable.com/docs/x/deep-dive-api-concepts#imx-timestamp-string) <a href="#imx-timestamp-string" id="imx-timestamp-string"></a>

The `IMX-Timestamp` can be generated by this example Javascript function:

Javascript

```
const timestamp = Math.floor(Date.now() / 1000).toString();
```

### `x-imx-eth-address` (string)[​](https://docs.x.immutable.com/docs/x/deep-dive-api-concepts#x-imx-eth-address-string) <a href="#x-imx-eth-address-string" id="x-imx-eth-address-string"></a>

This is the public Ethereum address of the user executing the transaction.

### `IMX-Signature` (string), `x-imx-eth-signature` (string), `auth_signature` (string)[​](https://docs.x.immutable.com/docs/x/deep-dive-api-concepts#imx-signature-string-x-imx-eth-signature-string-auth_signature-string) <a href="#imx-signature-string-x-imx-eth-signature-string-auth_signature-string" id="imx-signature-string-x-imx-eth-signature-string-auth_signature-string"></a>

💡STEPS:

* <mark style="color:blue;">Get Ethereum signer</mark>
* <mark style="color:blue;">Get message to be signed</mark>
* <mark style="color:blue;">Serialize the signature</mark>

#### 1. Get Ethereum signer[​](https://docs.x.immutable.com/docs/x/deep-dive-api-concepts#1-get-ethereum-signer) <a href="#id-1-get-ethereum-signer" id="id-1-get-ethereum-signer"></a>

Signers are abstractions of user accounts that can be used to sign transactions. A user's private key is required to generate them. Read more <mark style="color:blue;">here</mark>.

In order to generate the `IMX-Signature` and `x-imx-eth-signature` headers, we need an Ethereum signer for the user.

See <mark style="color:blue;">here</mark> on how to generate these signers.

#### 2. Get message[​](https://docs.x.immutable.com/docs/x/deep-dive-api-concepts#2-get-message) <a href="#id-2-get-message" id="id-2-get-message"></a>

Different messages are required by the different attributes:

<table><thead><tr><th width="341">Param</th><th>Message</th></tr></thead><tbody><tr><td><code>IMX-Signature</code></td><td><mark style="color:blue;">IMX-Timestamp</mark></td></tr><tr><td><code>x-imx-eth-signature</code></td><td><p>The message to be signed depends on each transaction. Typically, it contains information about the transaction that requires the user signature.<br><br>The messages required for the following endpoints are:</p><ul><li><mark style="color:blue;">Get a list of metadata refreshes</mark> - expects a message of <mark style="color:blue;">IMX timestamp</mark></li><li><mark style="color:blue;">Requesting a metadata refresh</mark> - expects a message of <mark style="color:blue;">IMX timestamp</mark></li><li><mark style="color:blue;">Get metadata refresh results</mark> - expects a message of <mark style="color:blue;">IMX timestamp</mark></li><li><mark style="color:blue;">Get metadata refresh errors</mark> - expects a message of <mark style="color:blue;">IMX timestamp</mark></li><li><mark style="color:blue;">createOrder</mark> - expects a message of <mark style="color:blue;">getSignableOrder</mark></li><li><mark style="color:blue;">cancelOrder</mark> - expects a message of <mark style="color:blue;">getSignableOrder</mark></li><li><mark style="color:blue;">createTransferV1</mark> - expects a message of <mark style="color:blue;">getSignableTransfer</mark></li><li><mark style="color:blue;">createTransfer</mark> - expects a message of <mark style="color:blue;">getSignableTransfer</mark></li><li><mark style="color:blue;">createWithdrawal</mark> - expects a message of <mark style="color:blue;">getSignableWithdrawal</mark></li><li><mark style="color:blue;">createTrade</mark> - expects a message of <mark style="color:blue;">getSignableTrade</mark></li><li><mark style="color:blue;">createExchangeTransfer</mark> - expects a message of <mark style="color:blue;">getExchangeSignableTransfer</mark></li></ul></td></tr><tr><td><code>auth_signature</code></td><td>See <mark style="color:blue;">below</mark></td></tr></tbody></table>

**How to get the message for the `auth_signature`?**[**​**](https://docs.x.immutable.com/docs/x/deep-dive-api-concepts#how-to-get-the-message-for-the-auth_signature)

The `auth_signature` param is used in the <mark style="color:blue;">mintTokens</mark> request.

1. Put together an object like the following Javascript example:

Javascript

```
const object = {
  contract_address: "string",
  royalties: [ // Optional
    {
      recipient: "string",
      percentage: "string",
    },
  ]
  users: [
    {
      ether_key: "string",
      tokens: [
        {
          id: "string",
          blueprint: "string",
          royalties: [ // Optional
            {
              recipient: "string",
              percentage: "string",
            },
          ]
        }
      ]
    }
  ],
};
```

2. Create a hash of that object that becomes the `message` to be signed to get the `auth_signature`:

Javascript

```
import { keccak256 } from '@ethersproject/keccak256';
import { toUtf8Bytes } from '@ethersproject/strings';

const message = keccak256(toUtf8Bytes(JSON.stringify(object)));
```

#### 3. Serialize the signature[​](https://docs.x.immutable.com/docs/x/deep-dive-api-concepts#3-serialize-the-signature) <a href="#id-3-serialize-the-signature" id="id-3-serialize-the-signature"></a>

Implement a function using the `signer` and `message` obtained in the previous steps like the following Typescript example:

Typescript

```
export async function signRaw(
  message: string,
  signer: Signer
): Promise<string> {
  const signature = deserializeSignature(await signer.signMessage(message));
  return serializeEthSignature(signature);
}
```

Where `deserializeSignature()` looks like:

Typescript

```
import BN from 'bn.js'; // https://www.npmjs.com/package/bn.js
import * as encUtils from 'enc-utils'; // https://www.npmjs.com/package/enc-utils

type SignatureOptions = {
  r: BN;
  s: BN;
  recoveryParam: number | null | undefined;
};

function importRecoveryParam(v: string): number | undefined {
  return v.trim()
    ? new BN(v, 16).cmp(new BN(27)) !== -1
      ? new BN(v, 16).sub(new BN(27)).toNumber()
      : new BN(v, 16).toNumber()
    : undefined;
}

function deserializeSignature(sig: string, size = 64): SignatureOptions {
  sig = encUtils.removeHexPrefix(sig);
  return {
    r: new BN(sig.substring(0, size), 'hex'),
    s: new BN(sig.substring(size, size * 2), 'hex'),
    recoveryParam: importRecoveryParam(sig.substring(size * 2, size * 2 + 2)),
  };
}
```

and `serializeEthSignature()` looks like:

Typescript

```
function serializeEthSignature(sig: SignatureOptions): string {
  // This is because golang appends a recovery param
  // https://github.com/ethers-io/ethers.js/issues/823
  return encUtils.addHexPrefix(
    encUtils.padLeft(sig.r.toString(16), 64) +
      encUtils.padLeft(sig.s.toString(16), 64) +
      encUtils.padLeft(sig.recoveryParam?.toString(16) || '', 2)
  );
}
```

### `stark_signature` (string)[​](https://docs.x.immutable.com/docs/x/deep-dive-api-concepts#stark_signature-string) <a href="#stark_signature-string" id="stark_signature-string"></a>

The `stark_signature` is required in the request body params of certain endpoints. It is obtained by using a Stark signer to sign the `payload_hash` produced in the response of the following corresponding endpoints:

| Action                    | <mark style="color:blue;">Endpoint(s) requiring</mark> <mark style="color:blue;"></mark><mark style="color:blue;">`stark_signature`</mark> | <mark style="color:blue;">Endpoint(s) providing</mark> <mark style="color:blue;"></mark><mark style="color:blue;">`payload_hash`</mark> <mark style="color:blue;"></mark><mark style="color:blue;">to be signed</mark> |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Create orders             | <mark style="color:blue;">createOrder</mark>                                                                                               | <p><mark style="color:blue;">getSignableOrderV1</mark><br><mark style="color:blue;">getSignableOrder</mark></p>                                                                                                        |
| Cancel orders             | <mark style="color:blue;">cancelOrder</mark>                                                                                               | <mark style="color:blue;">getSignableCancelOrder</mark>                                                                                                                                                                |
| Create transfers          | <p><mark style="color:blue;">createTransfer</mark><br><mark style="color:blue;">createTransferV1</mark></p>                                | <p><mark style="color:blue;">getSignableTransfer</mark><br><mark style="color:blue;">getSignableTransferV1</mark></p>                                                                                                  |
| Create withdrawals        | <mark style="color:blue;">createWithdrawal</mark>                                                                                          | <mark style="color:blue;">getSignableWithdrawal</mark>                                                                                                                                                                 |
| Create trades             | <mark style="color:blue;">createTrade</mark>                                                                                               | <mark style="color:blue;">getSignableTrade</mark>                                                                                                                                                                      |
| Create exchange transfers | <mark style="color:blue;">createExchangeTransfer</mark>                                                                                    | <mark style="color:blue;">getExchangeSignableTransfer</mark>                                                                                                                                                           |

💡STEPS:

* <mark style="color:blue;">Get message to be signed</mark>
* <mark style="color:blue;">Generate StarkSigner and sign the message</mark>

#### 1. Get message to be signed[​](https://docs.x.immutable.com/docs/x/deep-dive-api-concepts#1-get-message-to-be-signed) <a href="#id-1-get-message-to-be-signed" id="id-1-get-message-to-be-signed"></a>

Call the corresponding endpoint to the one requiring the `stark_signature` that gets the `payload_hash` to be signed (ie. the endpoint that provides the `payload_hash` for the <mark style="color:blue;">createWithdrawal</mark> endpoint is the <mark style="color:blue;">getSignableWithdrawal</mark> endpoint).

#### 2. Generate Stark signer and sign the message[​](https://docs.x.immutable.com/docs/x/deep-dive-api-concepts#2-generate-stark-signer-and-sign-the-message) <a href="#id-2-generate-stark-signer-and-sign-the-message" id="id-2-generate-stark-signer-and-sign-the-message"></a>

Use the Core SDK to generate the Stark signers. See instructions <mark style="color:blue;">here</mark>.

Use the Stark signer to sign the `payload_hash` in <mark style="color:blue;">Step 1:</mark>

* Typescript Core SDK
* Kotlin (JVM) Core SDK
* Swift Core SDK
* Golang Core SDK

```
const starkSignature = await starkSigner.signMessage(payloadHash);
```

[<br>](https://docs.x.immutable.com/docs/x/deep-dive-deposits-withdrawals)