Skip to main content

​
Base URLs

EnvironmentBase URL
Sandboxhttps://ramp-sandbox.hexarails.ai

​
Authentication

Every request must be authenticated using HMAC-SHA256 request signing. You receive an API key and secret during partner onboarding.

​
Required Headers

HeaderDescription
X-API-KeyYour API key
X-TimestampUnix timestamp in seconds
X-NonceA unique random string for each request
X-SignatureHMAC-SHA256 hex digest of the canonical string described on the Authentication page

​
Signature Algorithm

Build the canonical string with these newline-delimited parts, then sign it with HMAC-SHA256: 
METHOD
HOST
PATH
QUERY
BODY_SHA256_HEX
TIMESTAMP
NONCE
Use the exact host from the environment you call, keep query parameters in their original order, and use an empty body hash for GET and multipart/form-data requests. See the Authentication page for the full language examples.
The current OpenAPI file still lists api_secret as a security scheme. The narrative integration contract uses the secret as the HMAC signing key, not as a request header. Keep your implementation aligned with the signed-header flow shown here unless Coinut gives you an environment-specific override.
Requests with timestamps older than 60 seconds are rejected. Sync your server clock with NTP.

​
Authenticated Request Example

API_KEY="your_api_key"
API_SECRET="your_api_secret"
TIMESTAMP=$(date +%s)
NONCE="$(uuidgen | tr '[:upper:]' '[:lower:]')"
HOST="ramp.hexarails.ai"
METHOD="GET"
PATH="/balance"
QUERY=""
BODY_SHA256=""
PAYLOAD="${METHOD}\n${HOST}\n${PATH}\n${QUERY}\n${BODY_SHA256}\n${TIMESTAMP}\n${NONCE}"
SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$API_SECRET" | cut -d' ' -f2)

curl -X "$METHOD" "https://ramp.hexarails.ai/balance" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Nonce: $NONCE" \
  -H "X-Signature: $SIGNATURE"

​
Request & Response Format

  • All requests and responses use JSON with UTF-8 encoding.
  • Set Content-Type: application/json on every request.
  • Use POST for mutations and GET for reads unless specified otherwise.

​
Success Response

{
  "status": "SUCCESS",
  "data": { }
}

​
Error Response

{
  "status": "INVALID_PARAMETERS | UNAUTHORISED | FAILED",
  "message": "Human-readable description of the error"
}

​
HTTP Status Codes

CodeMeaning
200Request succeeded.
403Infrastructure access control blocked the request before application auth.
422Contract-defined application or validation error.

​
Pagination

List endpoints return paginated results using these fields:
FieldTypeDescription
pageNumintegerCurrent page number (1-based)
pageSizeintegerItems per page
totalintegerTotal matching records

​
Example Paginated Response

{
  "status": "SUCCESS",
  "data": {
    "list": [ /* items */ ],
    "pageNum": 1,
    "pageSize": 10,
    "total": 47
  }
}
Pass pageNum and pageSize as query parameters on list endpoints. pageSize defaults to 10 and caps at 100.

​
API Categories

CategoryDescriptionEndpoints
CommonBalance, configuration, health, webhook settings[/health](api-common#get-health)[/balance](api-common#get-balance)[/callback-url](api-common#get-callback-url)
CustomersCustomer onboarding and KYC verification[POST /customer/create](api-customers#post-customercreate)[GET /customer/detail](api-customers#get-customerdetail)[GET /customer/list](api-customers#get-customerlist)
Virtual AccountsFiat virtual accounts for receiving payments[POST /virtual-account/create](api-virtual-accounts#post-virtual-accountcreate)[GET /virtual-account/list](api-virtual-accounts#get-virtual-accountlist)[GET /virtual-account/detail](api-virtual-accounts#get-virtual-accountdetail)
Crypto AddressesDestination wallet addresses for payoutsPOST /crypto-address/addGET /crypto-address/listGET /crypto-address/detail
Deposit AddressesSource crypto addresses for customer depositsPOST /deposit-address/createGET /deposit-address/list
Bank AccountsCustomer bank accounts for fiat payoutsPOST /bank-account/addGET /bank-account/listGET /bank-account/detail
AutorampAutomated onramp and offramp flowsPOST /autoramp-flow/createGET /autoramp-flow/list
DepositsDeposit transaction monitoringGET /deposit/listGET /deposit/detail
TradesOTC trade records and historyGET /trade/listGET /trade/detail
PaymentsDirect fiat payments to beneficiariesPOST /payment/createGET /payment/list

​
Rate Limiting

Rate limits apply per API key. Exceeding the limit returns HTTP 429. Default limits are 100 requests per minute per key. Contact support to raise your limit.
If you hit a 429, wait for the Retry-After header (seconds) before retrying. Use exponential backoff with jitter in your client.