Payouts

Helix Payouts API documentation is focused on integrations where the partner/merchant is the end customer and possess a profile id of their own.

Payouts are used to transfer between supported currencies/tokens. For example GBP:BTC or RM:AXS.

There are a few steps which must be followed to create a payout.

Step 1: Create a quote

Quote fetches current mid-market exchange rate that will be used for your transfer. Quote also calculates our fee and estimated delivery time.

Request

Request Body

{
  "customExternalId": "YOUR UID HERE",
  "sourceCurrency": "USD",
  "sourceAmount": 100,
  "targetCurrency": "HTTP",
  "targetAddress": "0xcE3c9a3e7885fE4F11965356C36153772c60CBa7"
}

Reference

Field

Description

Format

customExternalId

UID - should be a reference to the quote for the connecting system to reconcile against. Acts as an idempoteny key for the quote. Resubmitting the same customExternalId will refresh the quote with the latest information. We would recommend using a library like uuid4 with prepended human friend string. USD:HTT::{uuid}

String

Source (sending) currency symbol.

String

Target (receiving) currency symbol.

String

targetAmount

Amount in target currency. (Optional)

Decimal

sourceAmount

Amount in source currency. Either sourceAmount or targetAmount is required, never both. (Optional)

Decimal

Avoiding duplicate quotes

We use customExternalId field to avoid duplicate transfer requests. When your first call fails (error or timeout) then you should use the same value in customExternalId field that you used in the original call when you are submitting a retry message. This way we can treat subsequent retry messages as repeat messages and will not create duplicate quotes to your account.

Response

FieldDescriptionFormat

quoteId

A unique reference to the quote created. You can only create one transfer per one quote.

You cannot use same quote uuid to create multiple transfers.

UID

merchantId

Merchant ID is your customer account.

UID

customExternalId

External ID provided by the merchant.

String

sourceCurrency

Source currency

String

sourceAmount

Calculated source exchanged amount

String

targetCurrency

Target currency

String

targetAmount

Calculated target exchanged amount

String

targetAddress

A valid EVM wallet address. Note: ENS domains are not supported.

String

expirationTime

Expiration date of the quote

Date

hlxFeeValue

Total Helix fee including all gas.

String

hlxFeePercentage

Percentage spread on target currency

String

estimateGas

Network gas feee

Number

Example Request

curl -X 'POST' \
  'https://api.hlx.network/api/v1/Payment/CreateQuote' \
  -H 'accept: text/plain' \
  -H 'Authorization: sk_test_yFxRegcl9dwb4TzLTmhKJJRon' \
  -H 'Content-Type: application/json' \
  -d '{
  "customExternalId": "3712997823",
  "sourceCurrency": "USD",
  "sourceAmount": 100,
  "targetCurrency": "TUSDT",
  "targetAddress": "0xcE3c9a3e7885fE4F11965356C36153772c60CBa7"
}'

Example Response

{
  "success": true,
  "data": {
    "QuoteId": "8edcb400-7a1e-404e-829d-e719b5446027",
    "merchantId": "b75ed2d4-0e76-4f92-b212-d008bda66d7c",
    "customExternalId": "3712997823",
    "sourceCurrency": "USD",
    "sourceAmount": 100,
    "targetCurrency": "TUSDT",
    "targetAmount": 100,
    "targetAddress": "0xcE3c9a3e7885fE4F11965356C36153772c60CBa7",
    "expirationTime": "2022-06-30T10:10:30.8463496+00:00",
    "status": 1,
    "hlxFeeValue": "30015.0000",
    "hlxFeePercentage": "15",
    "estimateGas": 34536
  },
  "errors": null
}

Step 2: Create a recipient account [PHASE 2]

Currently the recipient endpoint is planned for Phase 2, and will be used to improve the customer experience in the future.

  • Direct emails and updates from pending transfers

  • Grouping of transaction viewable in the Helix customer account

  • Improved KYC for required markets

Step 3: Create a transfer

A transfer is a payout order you make to a recipient account based on a quote.

Request

Request Body

{
  "id": "8edcb400-7a1e-404e-829d-e719b5446027" // quoteId
}
FieldDescriptionFormat

id

quoteId

String

Response

You need to save the transfer id for tracking its status later.

transferId

ID of the transfer

string($uuid)

quoteId

ID of the quote previously created

string($uuid)

customExternalId

Your external ID supplied with the quote

string

merchantId

Your UID

string($uuid)

tokenId

Internal reference of the token sent

string($uuid)

targetToken

Symbol

string

targetAmount

The amount a end customer will receive in their wallet

string

sourceAmount

The amount charged to the merchant for the transaction

string

targetAddress

The end customer wallet address

string

hlxFeeValue

The fee charged to the merchant

hlxFeePercentage

The overall percentage charged on the transaction

gasFee

Current Blockchain gas fee on the transaction

string

status

[1, 2, 3]

string

transactionHash

Transaction hash which can be used to find the transaction on the block explorers

string

Example Request

curl -X 'POST' \
  'https://api.hlx.network/api/v1/Payment/ProcessQuote' \
  -H 'accept: text/plain' \
  -H 'Authorization: sk_test_3C0IaepQwVMcAhSOWevfFgs3k' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "494de6a9-1250-4450-987c-d2520b73c0f2"
}'

Example Response

{
  "success": true,
  "data": {
    "transferId": "84e89b1b-150f-4faa-95be-a7b8a36b7c5c",
    "quoteId": "494de6a9-1250-4450-987c-d2520b73c0f2",
    "merchantId": "0f2ede0f-3c06-4f58-b983-a1a4e22f40b9",
    "tokenId": "d48c7373-8f1a-4d40-9f5e-6a474364fe01",
    "targetToken": "d48c7373-8f1a-4d40-9f5e-6a474364fe01",
    "targetAmount": "121.95",
    "sourceAmount": "100.00",
    "targetAddress": "0x4695CAfDc3e9719D438B83300599b5eE3E7dC93D",
    "gasFee": "3000",
    "status": "Processed",
    "transactionHash": "0xe183b606508cfd6f831ae7f1857f8236fcccfb203fcc5f6013bcbe4fbf3330ea"
  },
  "errors": null
}

Once a quote has been submitted it can't not be reused. Trying to submit again will return the following error.

{
  "success": false,
  "data": null,
  "errors": [
    "Quote status is not Open"
  ]
}

Step 4: Fund a transfer [PHASE 2]

Currently the recipient endpoint is planned for Phase 2, and will be used to improve the customer experience in the future.

Currently the fund transfer endpoint is planned for Phase 2, and will be used to support instant funding of from the source currency to the target without using a pre-funded credit account.

  • Instant exchange from source → target currencies

Step 5: Track transfer status

You can check your latest transfer status by polling this endpoint.

Example Request:

curl -X 'POST' \
  'https://api.hlx.network/api/v1/Payment/GetQuoteStatus?quoteId=494de6a9-1250-4450-987c-d2520b73c0f2' \
  -H 'accept: text/plain' \
  -H 'Authorization: sk_test_3C0IaepQwVMcAhSOWevfFgs3k' \
  -d '

Example Response:

{
  "success": true,
  "data": {
    "quoteId": "494de6a9-1250-4450-987c-d2520b73c0f2",
    "merchantId": "0f2ede0f-3c06-4f58-b983-a1a4e22f40b9",
    "customExternalId": "8976HUIJKH",
    "sourceCurrency": "USD",
    "sourceAmount": 100,
    "targetCurrency": "HTTP",
    "targetAmount": 121.95121951219512,
    "targetAddress": "0x4695CAfDc3e9719D438B83300599b5eE3E7dC93D",
    "expirationTime": "2022-07-20T11:32:02.764161Z",
    "status": 2,
    "hlxFeeValue": "30,005.00",
    "hlxFeePercentage": "5",
    "estimateGas": 0,
    "transactionHash": "0xe183b606508cfd6f831ae7f1857f8236fcccfb203fcc5f6013bcbe4fbf3330ea"
  },
  "errors": null
}

Last updated