Home
Guides
Developer Dashboard

Quote-based Transfers

Suggest Edits

Quote-based transfers require you to first create a transfer quote and then accept it to initiate the transfer. The transfer object will include the quote information, which is time-sensitive and will eventually expire.

Rails that provides quote-based transfers:

  • SOUTH_AMERICA_STANDARD

For example, USDC to BRL offramps are quote-based, as the conversion rate between USDC and BRL fluctuates. Let's take a look at how we can offramp from USDC to BRL:

To perform transfers between USDC and BRL, the user must first unlock the SOUTH_AMERICA_STANDARD rails by submitting KYC. Afterward, they need to Add a BRL Offramp Bank Account (PIX) before proceeding with any transfers. For guidance on how to submit KYC to unlock rails, refer to the Quickstart Guide (Sandbox) or the KYC Overview

After unlocking the SOUTH_AMERICA_STANDARD rails and creating a BRL offramp bank account (PIX), you can proceed with creating a transfer quote to initiate the offramp from USDC to BRL.

Create a Transfer Quote

Creating a transfer quote can be done using the regular transfer endpoints. In this case, you can simply call the Convert Stablecoin to Fiat endpoint to generate a transfer quote.

Request:

curl --location --request POST 'https://sandbox.hifibridge.com/transfer/crypto-to-fiat' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer zpka_xxxxx' \
--data '{
    "requestId": "77911c36-f951-40e9-a9f7-aef6d79c2701", 
    "sourceUserId": "f4fd2f10-2577-45cc-9e06-07ac9a74eb51", 
    "destinationAccountId": "aa41ec6a-0381-434d-9bf0-d3f052093e4d", 
    "sourceCurrency": "usdc",
    "destinationCurrency": "brl",
    "amount": 10, 
    "chain": "POLYGON_AMOY",
    "paymentRail": "pix"
}'

Response:

{
    "transferType": "CRYPTO_TO_FIAT",
    "transferDetails": {
        "id": "670aabcd-24ef-4e19-94b3-a8e92a27ce6d",
        "requestId": "814d56dc-f1ee-49d0-bc16-deda885d3f4e",
        "sourceUserId": "f4fd2f10-2577-45cc-9e06-07ac9a74eb51",
        "destinationUserId": "f4fd2f10-2577-45cc-9e06-07ac9a74eb51",
        "chain": "POLYGON_AMOY",
        "sourceCurrency": "usdc",
        "amount": 10,
        "destinationCurrency": "brl",
        "liquidationAddress": null,
        "destinationAccountId": "aa41ec6a-0381-434d-9bf0-d3f052093e4d",
        "transactionHash": null,
        "createdAt": "2024-11-26T19:24:56.69111+00:00",
        "updatedAt": "2024-11-26T19:24:56.69111+00:00",
        "status": "OPEN_QUOTE",
        "contractAddress": "0x4D423D2cfB373862B8E12843B6175752dc75f795",
        "sourceUser": {
            "email": "[email protected]",
            "lastName": "Man",
            "firstName": "Post",
            "businessName": null
        },
        "destinationUser": {
            "email": "[email protected]",
            "lastName": "Man",
            "firstName": "Post",
            "businessName": null
        },
        "destinationAccount": {
            "accountId": "aa41ec6a-0381-434d-9bf0-d3f052093e4d",
            "userId": "f4fd2f10-2577-45cc-9e06-07ac9a74eb51",
            "type": "pix",
            "name": "Brazilian Bank",
            "pixKey": "14947677768"
        },
        "failedReason": null,
        "fee": null,
        "quoteInformation": {
            "sendGross": {
                "amount": "10.00000000",
                "currency": "usdc"
            },
            "sendNet": {
                "amount": "9.90000000",
                "currency": "usdc"
            },
            "railFee": {
                "amount": "0.10000000",
                "currency": "usdc"
            },
            "receiveGross": {
                "amount": "56.94",
                "currency": "brl"
            },
            "receiveNet": {
                "amount": "56.94",
                "currency": "brl"
            },
            "rate": "5.7519",
            "expiresAt": "2024-11-26T19:29:59.800Z"
        }
    }
}

Let's take a closer look at the response object, specifically transferDetails:

  • id: The transfer ID, which you will use to accept the transfer quote and initiate the transfer.
  • status: "OPEN_QUOTE" indicates that the transfer has an open quote. The user should review and accept this quote before it expires to initiate the transfer.
  • quoteInformation:
    • sendGross: The total amount that will be withdrawn from the user’s wallet. This value should match the amount specified in the transferDetails.
    • sendNet: The final amount sent for conversion after deducting fees.
    • railFee: The fee deducted for the transfer. The currency sub-field indicates whether the fee is deducted before sending (usdc) or after receiving (brl).
    • receiveGross: The gross amount received after conversion.
    • receiveNet: The net amount received by the destination account after any fee deduction.
    • rate: The conversion rate applied to the conversion between the send currency and the receive currency.
    • expiresAt: When this quote expires.

For this particular transfer quote, the calculation starts from the amount of USDC to be withdrawn from the user's wallet to the amount of BRL to be deposited into the destination BRL offramp account:

(sendGross−railFee)×rate=receiveNet -> (10 - 0.1) x 5.7519 = 56.94

Accept Transfer Quote

To accept the transfer quote (wherestatusis"OPEN_QUOTE"), you can use the Accept Transfer Quote endpoint, passing in the transfer id.

Request:

curl --location --request PUT 'https://sandbox.hifibridge.com/transfer/crypto-to-fiat/acceptQuote?userId=f4fd2f10-2577-45cc-9e06-07ac9a74eb51&id=670aabcd-24ef-4e19-94b3-a8e92a27ce6d' \
--header 'Authorization: Bearer zpka_xxxxx'

Response:

{
    "transferType": "CRYPTO_TO_FIAT",
    "transferDetails": {
        "id": "670aabcd-24ef-4e19-94b3-a8e92a27ce6d",
        "requestId": "814d56dc-f1ee-49d0-bc16-deda885d3f4e",
        "sourceUserId": "f4fd2f10-2577-45cc-9e06-07ac9a74eb51",
        "destinationUserId": "f4fd2f10-2577-45cc-9e06-07ac9a74eb51",
        "chain": "POLYGON_AMOY",
        "sourceCurrency": "usdc",
        "amount": 10,
        "destinationCurrency": "brl",
        "liquidationAddress": null,
        "destinationAccountId": "aa41ec6a-0381-434d-9bf0-d3f052093e4d",
        "transactionHash": null,
        "createdAt": "2024-11-26T19:24:56.69111+00:00",
        "updatedAt": "2024-11-26T19:24:56.69111+00:00",
        "status": "CREATED",
        "contractAddress": "0x4D423D2cfB373862B8E12843B6175752dc75f795",
        "sourceUser": {
            "email": "[email protected]",
            "lastName": "Man",
            "firstName": "Post",
            "businessName": null
        },
        "destinationUser": {
            "email": "[email protected]",
            "lastName": "Man",
            "firstName": "Post",
            "businessName": null
        },
        "destinationAccount": {
            "accountId": "aa41ec6a-0381-434d-9bf0-d3f052093e4d",
            "userId": "f4fd2f10-2577-45cc-9e06-07ac9a74eb51",
            "type": "pix",
            "name": "Brazilian Bank",
            "pixKey": "14947677768"
        },
        "failedReason": null,
        "fee": null,
        "quoteInformation": {
            "sendGross": {
                "amount": "10.00000000",
                "currency": "usdc"
            },
            "sendNet": {
                "amount": "9.90000000",
                "currency": "usdc"
            },
            "railFee": {
                "amount": "0.10000000",
                "currency": "usdc"
            },
            "receiveGross": {
                "amount": "56.94",
                "currency": "brl"
            },
            "receiveNet": {
                "amount": "56.94",
                "currency": "brl"
            },
            "rate": "5.7519",
            "expiresAt": "2024-11-26T19:29:59.800Z"
        }
    }
}

After the quote is accepted, the status will changed to CREATED, and the transfer will be initiated using the accepted quote.

Updated 7 days ago