Skip to Content
Developer DocumentationOn/Offramp Integration

On/Off Ramp Integration Guide

Introduction & Getting Started

Overview

The BLOX On/Off Ramp API enables partners to seamlessly integrate fiat-to-MYRC and MYRC-to-fiat transactions into their platforms, providing users with a secure and efficient way to mint and burn MYRC.

Audience

This guide is intended for technical partners and developers who wish to enable On/Off Ramp functionality within their own applications or platforms.

Prerequisites

  • API Credentials: Request your API key from the BLOX team
  • Sandbox Access: Access to the test environment for integration and QA
  • Dependencies: Ensure your environment supports HTTPS requests and JSON parsing

Transaction Flow Overview

On-ramp

Off-ramp

Here are the main steps of the flow:

  1. Initiating a Transaction

    • The integration process begins on the partner’s interface, where the user selects deposit/withdrawal, leading them to the “Deposit” or “Withdraw” screen
    • On this screen, the application fetches the deposit/withdrawal limits. When the customer inputs a withdrawal amount, partner’s backend sends a quote request to display calculated amount, rate and fees

  2. Proceeding to Checkout

    • The checkout process is triggered next, where the partner’s backend creates the transaction and redirects user to the URL returned by BLOX’s API
    • BLOX’s interface will request a customer to complete several steps including authorization, KYC compliance, and providing bank account details. After fulfilling all necessary requirements, the widget should redirect back to the successRedirectUrl

  3. Transaction Approval (for offramp)

    • In partner’s interface, the user confirms the transaction natively. Following this, the user sends the MYRC to the transferAddress specified by BLOX

  4. Post-Transaction Handling

    • The partner backend should expect to receive a webhook notification indicating the different stages of the transaction flow, including whether the transaction was successful or failed. For successful transactions, the provider should monitor and listen for incoming on-chain transactions

Quick Start

  1. Obtain API Credentials: Contact your BLOX account manager or support to receive your API key.

  2. Set Up Your Environment:

    • Sandbox Base URL: https://api.sandbox.blox.my/v1
    • Production Base URL: https://api.blox.my/v1
    • Ensure your server can make outbound HTTPS requests.

  3. Test an API Call:

curl -X GET "https://api.sandbox.blox.my/v1/health" \
  -H "blox-api-key: <YOUR_API_KEY>"

Integration Requirements & Standards

Technical Requirements

  • Supported Languages: Any language capable of making HTTPS requests and handling JSON
  • API Version: Use the latest stable version unless otherwise specified
  • Security: All requests must be made over HTTPS

Compliance

  • KYC/AML: Ensure your platform complies with local KYC/AML regulations
  • Data Privacy: Obtain user consent for data sharing as required by law

Branding & UX Guidelines

  • Branding: Display the BLOX logos as per the Brand Guidelines
  • User Experience: Clearly inform users about transaction statuses and expected timelines

Authentication

API Key Authentication

All API requests require authentication via the blox-api-key header.

Header:

blox-api-key: <YOUR_API_KEY>

Request Signatures (RFC 9421)

All state-changing requests (POST, PUT, PATCH, DELETE) must include an RFC 9421 HTTP Message Signature. This uses asymmetric cryptography for enhanced security.

Required Headers for Signed Requests

HeaderDescription
Content-DigestSHA-256 hash of the canonicalized request body
Signature-InputDescribes which components are signed
SignatureThe cryptographic signature

Example Request

curl -X POST "https://api.blox.my/v1/checkout" \
  -H "blox-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Content-Digest: sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:" \
  -H "Signature-Input: sig1=(@method @path content-digest content-type);created=1704067200;keyid=\"your_key_id\";alg=\"ed25519\"" \
  -H "Signature: sig1=:BASE64_SIGNATURE:" \
  -d '{"amount": 15000, ...}'

For complete implementation details, see the Request Signature documentation.

Best Practices

  • Always use HTTPS for all API traffic
  • Keep your private signing key secure on your server
  • Rotate API keys periodically
  • Never share your private key publicly

API Endpoints Overview

1. Quote

  • Endpoint: POST /onramp/quotes
  • Purpose: Get pricing for conversions before creating a transaction

2. Deposits (On-ramp)

  • Endpoint: POST /onramp/deposits
  • Purpose: Initiate fiat-to-crypto transactions

3. Withdrawals (Off-ramp)

  • Endpoint: POST /onramp/withdrawals
  • Purpose: Initiate crypto-to-fiat transactions

4. Transactions

  • Endpoint: GET /onramp/transactions/{id}
  • Purpose: Retrieve transaction status and details

Webhooks

Overview

Webhooks allow your platform to receive real-time updates about transaction events, such as completion or failure.

Setting Up Webhooks

  • Register Endpoint: Provide your webhook URL to BLOX support or via the partner dashboard
  • Security: Each webhook request includes an X-Signature header for verification

Event Types

Transaction Completed

{
  "event": "transaction.completed",
  "transaction_id": "txn_001",
  "status": "completed",
  "details": { ... }
}

Transaction Failed

{
  "event": "transaction.failed",
  "transaction_id": "txn_002",
  "status": "failed",
  "reason": "Insufficient funds"
}

Best Practices

  • Verify Signatures: Always validate the X-Signature header to ensure authenticity
  • Idempotency: Handle duplicate webhook events gracefully
  • Respond Quickly: Return a 200 OK status to acknowledge receipt

Error Handling

Common Error Codes

  • 401 Unauthorized – Invalid API key
  • 400 Bad Request – Missing or invalid parameters
  • 500 Internal Server Error – Unexpected error

Next Steps

  1. Explore the API Reference: Check out the detailed endpoint documentation
  2. Test in Sandbox: Use the sandbox environment to test your integration
  3. Set Up Webhooks: Configure webhook endpoints for real-time updates
  4. Go Live: Once testing is complete, switch to production environment

Resources

Last updated
Webhooks