Fiat-to-Fiat Conversions (Request Chaining)

The Centiiv Protocol API is designed around individual on-ramp (Fiat → Crypto) and off-ramp (Crypto → Fiat) building blocks. By linking these two blocks together, you can facilitate direct Fiat-to-Fiat conversions (e.g., Nigerian Naira [NGN] to Chinese Yuan [CNY]) using stablecoins as the underlying settlement bridge.

This guide explains how to chain an on-ramp request and an off-ramp request so that a user’s local fiat payment automatically triggers a fiat disbursement in another currency.

The Chaining Mechanism

The bridge works by passing the temporary deposit address generated by the off-ramp request as the destination address for the on-ramp request.

Step-by-Step Implementation

For this example, we will convert NGN (Fiat Input) to CNY via Alipay (Fiat Output) using USDC on the Stellar network.

Step 1: Create the Off-Ramp Request (USDC → CNY)

First, define the final payout parameters. This request specifies the beneficiary's Chinese Alipay account and compliance details.

• Endpoint: POST /requests
• Purpose: Secure the destination details and acquire the deposit wallet address.

Request Payload

{
  "fromAsset": "USDC",
  "toAsset": "CNY",
  "amount": 100,
  "network": "STELLAR",
  "refundAddress": "GCFXH5C3YQBAW7OKL2AVZFYJ6IHLZN4SXKTWRVQPQG3E5QJWZ7M2UW3K",
  "beneficiary": {
    "externalId": "user_cn_112",
    "destination": {
      "type": "ALIPAY",
      "accountNumber": "+8618112292223",
      "accountName": "Xu Xing",
      "remittancePurpose": "FAMILY_SUPPORT",
      "sender": {
        "type": "INDIVIDUAL",
        "firstName": "Chan",
        "lastName": "Ling",
        "nationalityCountry": "CN",
        "countryOfBirth": "CN",
        "country": "CN",
        "dateOfBirth": "1997-11-12",
        "idType": "PASSPORT",
        "idNumber": "B07539234",
        "postCode": "213000",
        "address": "Xin Hua You Ju Dui Mian"
      }
    }
  }
}

Response (Abridged)

The response returns a temporaryWallet containing the publicAddress. Copy this address, as it will be the destination for the next step.

{
  "id": "offramp_req_998877",
  "status": "PENDING",
  "type": "OFFRAMP",
  "fromAsset": "USDC",
  "toAsset": "CNY",
  "amount": 100,
  "temporaryWallet": {
    "publicAddress": "GDQWI6FKB72DPOJE4CGYCFQZKRPQQIOYXRMZ5ELVFXVVMTHWES2SJ7YT",
    "network": "STELLAR",
    "isTestnet": false,
    "expiresAt": "2026-07-29T10:30:00.000Z"
  }
}

Step 2: Create the On-Ramp Request (NGN → USDC)

Next, initialize the funding leg. You will direct the on-ramp settlement to deliver USDC directly to the deposit address generated in Step 1.

• Endpoint: POST /requests
• Purpose: Generate the virtual bank account details for the funding user.

Request Payload

Set the destinationAddress to the publicAddress obtained from the Step 1 response.

{
  "fromAsset": "NGN",
  "toAsset": "USDC",
  "amount": 150000,
  "network": "STELLAR",
  "destinationAddress": "GDQWI6FKB72DPOJE4CGYCFQZKRPQQIOYXRMZ5ELVFXVVMTHWES2SJ7YT",
  "sender": {
    "externalId": "user_67890",
    "fullName": "Jane Smith",
    "email": "[email protected]",
    "phone": "+2348012345678"
  }
}

Response (Abridged)

This response provides the virtual account information. Present these banking details to the user so they can send the local currency (NGN) transfer.

{
  "id": "onramp_req_112233",
  "status": "PENDING",
  "type": "ONRAMP",
  "fromAsset": "NGN",
  "toAsset": "USDC",
  "amount": 150000,
  "temporaryWallet": {
    "virtualAccountNumber": "8012345678",
    "virtualAccountName": "Cent Protocol / Jane Smith",
    "virtualBankName": "Wema Bank",
    "virtualBankCode": "035"
  }
}

Step 3: Payer Execution

Provide the virtual bank details to the paying user. Once the user transfers 150,000 NGN to Wema Bank:

1. The protocol detects the incoming NGN transaction.
2. The system triggers the on-ramp request fulfillment and routes the corresponding USDC to the destinationAddress (GDQWI6FKB...).
3. The off-ramp system detects the incoming USDC deposit on Stellar at GDQWI6FKB....
4. The off-ramp request transitions to PROCESSING, and the LP initiates the CNY payout to the Alipay account.

Important Integration Considerations

1. Request Expiration Window

Both requests expire after 30 minutes if no deposits are detected. Because the off-ramp request is created first, its timer starts running slightly before the on-ramp timer. Ensure the funding user completes their fiat transfer promptly to prevent the receiving wallet from expiring.

2. Matching Network and Assets

The on-ramp's toAsset and network must match the off-ramp's fromAsset and network. Mixing assets or chains (e.g., trying to route an Arbitrum USDC on-ramp directly into a Stellar USDC off-ramp deposit wallet) will result in stuck or lost funds.

3. Sizing and Slippage (Calculating Amounts)

Because conversion rates and LP fees apply to both steps, the actual stablecoin amount delivered by the on-ramp must meet the minimum requirement of the off-ramp.

• Use POST /public/quote for the on-ramp leg (NGN → USDC) to understand how much stablecoin is expected to land in the destination wallet for a given fiat input.
• Verify that the expected output of the on-ramp matches or exceeds the required amount of the off-ramp request to ensure successful downstream execution.