> For the complete documentation index, see [llms.txt](https://vnx.gitbook.io/vnx-global/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://vnx.gitbook.io/vnx-global/developer/guides/integrate-stablecoin-mint.md).

# Integrate Stablecoin Mint

*Fund your VNX account in fiat or crypto and mint VCHF or VGBP for your own treasury — delivered to your Platform balance or a whitelisted external wallet you control.*

## Use case and audience

You are a treasury, exchange, or fintech that holds a **direct account with VNX** and needs to mint VNX stablecoins on demand against your own fiat or crypto funding. This is a direct client↔VNX relationship: **you are the Customer of record** who funds, orders, and receives the tokens. You are not minting on behalf of your own end-users — the mint credits *your* balance, against *your* KYB and *your* signed order. What you do with the tokens afterward (hold them in treasury, distribute them through your own product, settle with counterparties) is outside this flow and governed by your own agreements.

VNX runs the regulated leg — moving your fiat into the fiduciary reserve and broadcasting the on-chain mint — while you orchestrate the ordering, funding, and reconciliation on your side. This guide covers both fiat and crypto funding paths, both fulfilment options (new issuance and proprietary trade), and delivery to either your Platform balance or a whitelisted external wallet. VCHF/VGBP minimum issuance is GBP 100,000.

## Architecture

See the verified flow in [Mint Flow](/vnx-global/developer/flows/mint-flow.md). The condensed view:

```mermaid
sequenceDiagram
    participant App as Your service
    participant V as VNX API
    participant FB as Fiduciary Bank (reserve)
    participant CCP as External regulated provider
    participant W as Your wallet / balance
    App->>V: POST /private/mintTokens (ECDSA-signed)
    alt Fiat funding present
      V->>FB: Move your fiat to reserve
      FB-->>V: Reserve increased
      V-->>W: Mint to your wallet
      App->>V: Poll /private/querySupplyChanges
    else Crypto funding present
      V->>CCP: Convert your crypto → fiat
      CCP-->>V: Fiat
      V-->>W: Mint to your wallet
      App->>V: Poll /private/querySupplyChanges
    end
```

## Prerequisites

* Your own KYB cleared and Stablecoin Services Agreement signed with VNX.
* An ECDSA key-pair registered with VNX; your private key signs each request (see [Authentication](/vnx-global/developer/concepts/authentication.md)).
* A `User-Agent` string on every request and adherence to the 1 req/sec per-public-key rate limit.
* For external wallet delivery: at least one of *your own* addresses whitelisted per chain, with Travel Rule originator data captured.
* For VGBP: minimum issuance ≥ GBP 100,000.

## Walkthrough

{% stepper %}
{% step %}

## Sign every request

Every `/private/*` request carries three headers plus a `User-Agent`:

* `x-app-public-key` — your registered public key.
* `x-app-nonce` — an always-increasing uint64 (UNIX milliseconds).
* `x-app-signed-data` — base64url ECDSA-SHA256 signature over the URI path + canonical-JSON POST data + nonce.

Canonical JSON sorts object keys lexicographically (recursively); array order is preserved. Most `/private/*` calls use `Content-Type: application/x-www-form-urlencoded`. A signed `mintTokens` request looks like:

```http
POST /api/v1/private/mintTokens HTTP/1.1
Host: api.vnx.io
Content-Type: application/x-www-form-urlencoded
User-Agent: MyClient/1.0
x-app-public-key: <public_key>
x-app-nonce: 1708881600002
x-app-signed-data: <base64url_signature>

asset=VCHF&blockchain=ETH&quantity=100000
```

{% endstep %}

{% step %}

## Fund your Platform account

For fiat funding, wire fiat from your bank to VNX's bank account. Funds credit your Platform balance after due diligence.

For crypto funding, send crypto to your VNX transitional wallet address.
{% endstep %}

{% step %}

## Submit a mint order

```bash
curl -X POST https://api.vnx.io/api/v1/private/mintTokens \
  -H "User-Agent: MyClient/1.0" \
  -H "x-app-public-key: ${PUBLIC_KEY}" \
  -H "x-app-nonce: ${NONCE}" \
  -H "x-app-signed-data: ${SIGNATURE}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "asset=VCHF" \
   "blockchain=ETH" \
   "quantity=100000"
```

```json
{
  "timestamp": "2026-05-07T16:00:00Z",
  "txid": "0xdef...",
  "requestid": "req_01HV...",
  "fee": "0",
  "spent": "100000.00",
  "spent_currency": "CHF"
}
```

{% endstep %}

{% step %}

## Poll for status

There are no webhooks. Poll `/private/querySupplyChanges` to follow the mint through to settlement; match the entry by `requestid` or `txid`, then update your own treasury ledger once it is settled.

```bash
curl -X POST https://api.vnx.io/api/v1/private/querySupplyChanges \
  -H "User-Agent: MyClient/1.0" \
  -H "x-app-public-key: ${PUBLIC_KEY}" \
  -H "x-app-nonce: ${NONCE}" \
  -H "x-app-signed-data: ${SIGNATURE}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "asset=VCHF"
```

Respect the 1 req/sec rate limit when polling; back off on errors (`{code, status, message}`).
{% endstep %}

{% step %}

## Compliance hold path

If a mint is parked for compliance (Travel Rule timeout, sanctions hit, EDD required), `querySupplyChanges` reflects the held state. Escalate to operations; coordinate with VNX support.
{% endstep %}

{% step %}

## Crypto funding nuance

When you fund with BTC or ETH, VNX converts to fiat through the External regulated provider and only then mints; expect \~3 hours and Travel Rule data capture for the inbound leg.
{% endstep %}
{% endstepper %}

## Test in UAT

Use the test base URL `https://api.uat.vnx.io/api/v1/` with your UAT credentials. Sign requests exactly as in production.

```bash
# Mint VCHF 1,000 on Ethereum
curl -X POST https://api.uat.vnx.io/api/v1/private/mintTokens \
  -H "User-Agent: MyClient/1.0" \
  -H "x-app-public-key: ${PUBLIC_KEY}" \
  -H "x-app-nonce: ${NONCE}" \
  -H "x-app-signed-data: ${SIGNATURE}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "asset=VCHF" \
   "blockchain=ETH" \
   "quantity=1000"
```

Expected UAT effects:

* A response with `txid` and `requestid`.
* `querySupplyChanges` shows the new mint, settling to completed.

## Troubleshooting

| Symptom                               | Likely cause                                        | Fix                                          |
| ------------------------------------- | --------------------------------------------------- | -------------------------------------------- |
| 400 `min_amount_below_threshold`      | VCHF/VGBP < GBP 100,000                             | Raise amount                                 |
| 403 `external_wallet_not_whitelisted` | Address not whitelisted/Travel Rule missing         | Whitelist + capture data                     |
| 401 signature/nonce error             | Bad signature, stale nonce, or wrong canonical JSON | Recompute over path + canonical body + nonce |
| Held entry in `querySupplyChanges`    | AML/sanctions/Travel Rule                           | Coordinate with VNX support                  |
| 429 rate limited                      | Exceeded 1 req/sec per public key                   | Throttle and back off                        |
| Long delay on crypto-funded mint      | Travel Rule exchange                                | Up to several hours; poll status             |

## Production checklist

* Always-increasing nonce (UNIX ms) per request; never reuse or decrease.
* Correct canonical-JSON serialization before signing every request.
* Rate-limit budget mapped to 1 req/sec; back off on 429 and `{code, status, message}` errors.
* Audit log captures `requestid`, `txid`, and nonce.
* Status reconciliation by polling `querySupplyChanges`.
* Travel Rule data validated at request time, not at hold time.
* Operational runbook for compliance holds.

## References

* [Mint Flow](/vnx-global/developer/flows/mint-flow.md)
* [Transfers](/vnx-global/developer/api/transfers.md)
* [Travel Rule](/vnx-global/developer/concepts/travel-rule.md)
* [Minting and Redemption](/vnx-global/institutional/products/minting-and-redemption.md)
* [Glossary](/vnx-global/glossary.md)