# API Integration

## Prerequisites

* Your business account with Inqud is set up, complete with API tokens configured.
* The Crypto Widget has been established and configured within the Inqud platform.
* The Crypto Widget is active.
* **Static Address Payments** web-hook is configured.

### Workflow

<figure><img src="https://2493659114-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MVvChLJdAqFu9uz7E-7%2Fuploads%2FrEpsGwRPHXPurqOXmOTa%2Fimage.png?alt=media&#x26;token=71243767-aca7-4771-8a36-c094a0a80b67" alt=""><figcaption></figcaption></figure>

### Payment status transition

<figure><img src="https://2493659114-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MVvChLJdAqFu9uz7E-7%2Fuploads%2F66ukgseTeC6A2vtxs34M%2FSlide%2016_9%20-%20346.png?alt=media&#x26;token=6f175aea-9ba4-4a04-b816-4102aa8a8d97" alt=""><figcaption></figcaption></figure>

### Integration

#### 1. Create static address(es) through Inqud API

[Create static bundle API Reference](https://apireference.inqud.com/#tag/crypto-acquiring-static-addresses/operation/user_crypto-acquiring-static_create-bundle)

{% hint style="info" %}
Static addresses are created within **static address bundles**, each containing multiple unique addresses per blockchain/address type. A bundle is identified by a merchant-supplied `referenceId` and represents a set of addresses a single user can use to send funds across different blockchains.
{% endhint %}

{% tabs %}
{% tab title="Single Static Address" %}
Request Example:\
\
POST `https://api.inqud.com/v1/user/crypto-acquiring/{projectId}/static/bundles`

{% hint style="info" %}
`projectId` is the ID of the widget
{% endhint %}

| Header             | Value            |
| ------------------ | ---------------- |
| X-Token-API-Id     | {tokenApiId}     |
| X-Token-API-Secret | {tokenApiSecret} |

Request Body Example:

```json
{
  "allEnabledAssets": false,
  "assets": [
    "ETHEREUM_USDT"
  ],
  "referenceId": "1234567890"
}
```

Response Example:

```json
{
  "referenceId": "1234567890",
  "id": "CASB-fa46e305-5d61-49f3-ad40-55254ee897d9",
  "addresses": [
    {
      "id": "UBADR-fd06b12f-9663-4b96-a6a7-1de219e7485f",
      "asset": "ETHEREUM_USDT",
      "address": "0x0b1b0856be15a7b1d613fedb2a139a519c1697a4",
      "active": true,
      "values": {
        "minLimit": 20,
        "percentFee": 0,
        "fixedFee": 0,
        "networkFeeEstimate": 4.75
      },
      "createdAt": "2025-02-05T16:45:05.697795853Z"
    }
  ],
  "addressesByAsset": {
    "ETHEREUM_USDT": {
      "id": "UBADR-fd06b12f-9663-4b96-a6a7-1de219e7485f",
      "asset": "ETHEREUM_USDT",
      "address": "0x0b1b0856be15a7b1d613fedb2a139a519c1697a4",
      "active": true,
      "values": {
        "minLimit": 20,
        "percentFee": 0,
        "fixedFee": 0,
        "networkFeeEstimate": 4.75
      },
      "createdAt": "2025-02-05T16:45:05.697795853Z"
    }
  },
  "deactivatedAddresses": [],
  "deactivatedAddressesByAsset": {},
  "assetsMeta": {
    "ETHEREUM_USDT": {
      "name": "ETHEREUM_USDT",
      "currency": "USDT",
      "blockchain": "ETHEREUM",
      "tokenStandard": "ERC-20",
      "contractAddress": "0xf884B63227D3427677c7b045370Bb269FabF1FA7"
    }
  },
  "createdAt": "2025-02-05T16:45:05.569881215Z"
}
```

{% endtab %}

{% tab title="Multiple Static Addresses " %}
Request Example:\
\
POST `https://api.inqud.com/v1/user/crypto-acquiring/{projectId}/static/bundles`

{% hint style="info" %}
`projectId` is the ID of the widget
{% endhint %}

| Header             | Value            |
| ------------------ | ---------------- |
| X-Token-API-Id     | {tokenApiId}     |
| X-Token-API-Secret | {tokenApiSecret} |

Request Body Example:

```json
{
  "allEnabledAssets": true,
  "referenceId": "12345678901"
}
```

{% hint style="info" %}
If `allEnabledAssets` is **true**, addresses will be generated for all assets enabled in the project.
{% endhint %}

Response Example:

```json
{
  "referenceId": "12345678901",
  "id": "CASB-bdb1c4dd-72a2-415b-9899-1f6fc8c538db",
  "addresses": [
    {
      "id": "UBADR-00962cec-b115-43ad-97b6-06400028a007",
      "asset": "ETHEREUM_USDT",
      "address": "0x395029b450234e62711faa558d673e3bc541b971",
      "active": true,
      "values": {
        "minLimit": 20,
        "percentFee": 0,
        "fixedFee": 0,
        "networkFeeEstimate": 10.69
      },
      "createdAt": "2025-02-05T16:53:28.527686Z"
    },
    {
      "id": "UBADR-00962cec-b115-43ad-97b6-06400028a007",
      "asset": "ETHEREUM_USDC",
      "address": "0x395029b450234e62711faa558d673e3bc541b971",
      "active": true,
      "values": {
        "minLimit": 27.993455,
        "percentFee": 0,
        "fixedFee": 0,
        "networkFeeEstimate": 27.993455
      },
      "createdAt": "2025-02-05T16:53:28.527686Z"
    },
    {
      "id": "UBADR-d94ee36e-7408-400d-812f-94250bb1ce5c",
      "asset": "SOLANA_USDC",
      "address": "FcVtzm5w35Xkoo6EyhyhDRg4ydKsFtpDw3kZe3JVxfA1",
      "active": true,
      "values": {
        "minLimit": 1,
        "percentFee": 0,
        "fixedFee": 0,
        "networkFeeEstimate": 0.00402
      },
      "createdAt": "2025-02-05T16:53:28.867788Z"
    },
    {
      "id": "UBADR-b0601997-9430-4bff-9a4c-6db33eaec9f4",
      "asset": "TRON_USDT",
      "address": "TDSxVHbro74fdJhdLopkycSNLxsb6tXs3p",
      "active": true,
      "values": {
        "minLimit": 10,
        "percentFee": 10,
        "fixedFee": 1,
        "networkFeeEstimate": 3.09
      },
      "createdAt": "2025-02-05T16:53:28.999177Z"
    }
  ],
  "addressesByAsset": {
    "ETHEREUM_USDT": {
      "id": "UBADR-00962cec-b115-43ad-97b6-06400028a007",
      "asset": "ETHEREUM_USDT",
      "address": "0x395029b450234e62711faa558d673e3bc541b971",
      "active": true,
      "values": {
        "minLimit": 20,
        "percentFee": 0,
        "fixedFee": 0,
        "networkFeeEstimate": 10.69
      },
      "createdAt": "2025-02-05T16:53:28.527686Z"
    },
    "ETHEREUM_USDC": {
      "id": "UBADR-00962cec-b115-43ad-97b6-06400028a007",
      "asset": "ETHEREUM_USDC",
      "address": "0x395029b450234e62711faa558d673e3bc541b971",
      "active": true,
      "values": {
        "minLimit": 27.993455,
        "percentFee": 0,
        "fixedFee": 0,
        "networkFeeEstimate": 27.993455
      },
      "createdAt": "2025-02-05T16:53:28.527686Z"
    },
    "SOLANA_USDC": {
      "id": "UBADR-d94ee36e-7408-400d-812f-94250bb1ce5c",
      "asset": "SOLANA_USDC",
      "address": "FcVtzm5w35Xkoo6EyhyhDRg4ydKsFtpDw3kZe3JVxfA1",
      "active": true,
      "values": {
        "minLimit": 1,
        "percentFee": 0,
        "fixedFee": 0,
        "networkFeeEstimate": 0.00402
      },
      "createdAt": "2025-02-05T16:53:28.867788Z"
    },
    "TRON_USDT": {
      "id": "UBADR-b0601997-9430-4bff-9a4c-6db33eaec9f4",
      "asset": "TRON_USDT",
      "address": "TDSxVHbro74fdJhdLopkycSNLxsb6tXs3p",
      "active": true,
      "values": {
        "minLimit": 10,
        "percentFee": 10,
        "fixedFee": 1,
        "networkFeeEstimate": 3.09
      },
      "createdAt": "2025-02-05T16:53:28.999177Z"
    }
  },
  "deactivatedAddresses": [],
  "deactivatedAddressesByAsset": {},
  "assetsMeta": {
    "ETHEREUM_USDT": {
      "name": "ETHEREUM_USDT",
      "currency": "USDT",
      "blockchain": "ETHEREUM",
      "tokenStandard": "ERC-20",
      "contractAddress": "0xf884B63227D3427677c7b045370Bb269FabF1FA7"
    },
    "ETHEREUM_USDC": {
      "name": "ETHEREUM_USDC",
      "currency": "USDC",
      "blockchain": "ETHEREUM",
      "tokenStandard": "ERC-20",
      "contractAddress": "0xfe9F7754d3F16a1554CFB76029c570BFD92bE5e9"
    },
    "SOLANA_USDC": {
      "name": "SOLANA_USDC",
      "currency": "USDC",
      "blockchain": "SOLANA",
      "tokenStandard": "SPL",
      "contractAddress": "ZHGFeqQCas2bnP9CynHa4Gy8XP1YxnmQv24d5TwvGZi"
    },
    "TRON_USDT": {
      "name": "TRON_USDT",
      "currency": "USDT",
      "blockchain": "TRON",
      "tokenStandard": "TRC-20",
      "contractAddress": "TLEf8dueuu5oiRs51exXiXHaTfafRQar7j"
    }
  },
  "createdAt": "2025-02-05T16:53:28.424867Z"
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
The endpoint follows a **"getOrCreate"** approach. On the first call with a specific `referenceId`, it creates a new bundle with static addresses. Subsequent calls with the same `referenceId` return the existing bundle. If an address for a requested asset is missing, it will generate and add it to the existing bundle.
{% endhint %}

{% hint style="info" %}
The bundle reuses static addresses when possible. For example, if an Ethereum USDT address exists, a Polygon USDC address will be the same address. This allows a user to send different tokens across multiple blockchains using a single address.
{% endhint %}

{% hint style="info" %}
If any static address in the bundle is disabled (e.g., due to AML rule violations), the endpoint will return a newly generated address for that asset.
{% endhint %}

The following fields in the response are the most important:

| Column                                 | Desciption                                                                                                                |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| referenceId                            | Merchant-provided ID used to track incoming payments                                                                      |
| addresses                              | List of static addresses in the bundle                                                                                    |
| addresses\[].address                   | Static address for end-user payments                                                                                      |
| addresses\[].active                    | **true** if the address can process deposits immediately; **false** if deposits may be delayed or temporarily unprocessed |
| addresses\[].values.minLimit           | Minimum amount the end user must send in a single transaction; otherwise, the payment will fail                           |
| addresses\[].values.percentFee         | A percentage fee is deducted from the incoming transaction amount                                                         |
| addresses\[].values.fixedFee           | A fixed fee is deducted from the incoming transaction amount                                                              |
| addresses\[].values.networkFeeEstimate | An estimated fee deducted from the incoming transaction amount to cover Inqud's transfer costs from the address           |
| addressesByAsset                       | Basically, the same as addresses but grouped by assets                                                                    |

#### 2. Receive a webhook when a new payment arrives

When an end user sends crypto to the assigned static address, you receive a webhook upon payment detection by the Inqud system.

{% content-ref url="web-hooks" %}
[web-hooks](https://docs.inqud.com/crypto-static-addresses/integration/web-hooks)
{% endcontent-ref %}

#### 3. \[Optional] Convert the payment amount to the desired currency

Inqud does not currently convert payment amounts to other currencies. Use a separate endpoint for conversion if needed.

[Get rate API Reference](https://apireference.inqud.com/#tag/crypto-acquiring-rates/operation/user_crypto-acquiring-rate)

Request Example:

GET `https://api.inqud.com/v1/user/crypto-acquiring/rates/{baseAsset}/{quoteAsset}`

{% hint style="info" %}
`projectId` is the ID of the widget
{% endhint %}

| Header             | Value            |
| ------------------ | ---------------- |
| X-Token-API-Id     | {tokenApiId}     |
| X-Token-API-Secret | {tokenApiSecret} |

Response Example:

```json
{
  "baseAsset": "BTC",
  "quoteAsset": "USD",
  "rate": 100100.1
}
```