# 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)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://xpansionchain-1.gitbook.io/xpansionchain/key-concepts/deep-dive-into-api-concepts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.