Comment on page

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
Oops, something is missing.We could not find the original source to display this content.
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
​sourceCurrency​
Source (sending) currency symbol.
String
​targetCurrency​
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
Field
Description
Format
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
Oops, something is missing.We could not find the original source to display this content.
Request Body
{
  "id": "8edcb400-7a1e-404e-829d-e719b5446027" // quoteId
}
Field
Description
Format
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.
Oops, something is missing.We could not find the original source to display this content.
​
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
}
​

Field	Description	Format
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

Field	Description	Format
id	quoteId	String

Quick Start - Previous

Payments

Next - Quick Start

Helix Dashboard

Last modified 1yr ago

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
sourceCurrency	Source (sending) currency symbol.	String
targetCurrency	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

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