Genesis Blockchain

Genesis Exchange Integration Guide

This document provides all the necessary technical instructions and API usage guidelines for integrating the Genesis Blockchain (Genesis) asset onto your exchange platform.

API Architecture: Our integration endpoint provides all necessary RPC-like functionalities through a modern, standard, and easy-to-use RESTful API. All responses are in application/json format.

Security: All API requests must be made over HTTPS.

Rate Limiting: A rate limit of 30 requests per minute per IP address is enforced. Exceeding this limit will result in a 429 Too Many Requests error response.

Step 1: Onboarding & Authentication

The first step is to obtain an API Key with corporate permissions. This is a straightforward self-service and approval process:

  1. Sign Up on the Dashboard: Log in or create a new account on the Genesis Dashboard.
  2. Generate Your API Key: Navigate to the API section within your dashboard and generate a new API Key (X-API-KEY).
  3. Request Business Elevation: Contact the Genesis support team to request that your account be elevated to "Business" status. This is a required step to grant your API Key the necessary permissions for corporate actions, such as creating sub-wallets for your users.

⚠️ Important: Only after your account is approved as a Business account will your API Key be authorized to perform critical exchange operations.

Step 2: Deposit Process

Follow these steps to generate deposit addresses for your users and monitor for incoming funds.

2.1. Generate a Deposit Address

Call this endpoint to generate a unique deposit address for each of your users.

Endpoint: POST /api/advanced/wallet/create-sub

Header:

X-API-KEY: your_business_approved_api_key

Success Response:

{
  "Address": "GNS...",
  "Mnemonic": "word1 word2 ... word12",
  "PrivateKey": "...",
  "PublicKey": "...",
  "CreatedAt": "..."
}

🔥 CRITICAL: You must securely store the returned PrivateKey and associate it with the user's account. This key grants full control over the funds in this address and is required for sweep operations.

2.2. Monitor for Deposits

Periodically poll this endpoint to check for new user deposits.

Endpoint: GET /api/advanced/balance/{walletAddress}

Success Response:

{
  "Address": "GNS...",
  "Balance": 123.45
}

Step 3: Withdrawal Process

To process user withdrawals, you must use the signed transaction model. This is an industry-standard, highly secure method that ensures your hot wallet's private key never leaves your server environment.

3.1. Create and Sign the Transaction (On Your Server)

  1. Construct a plain text message string in the exact format: "{senderAddress}->{receiverAddress}:{amount}". The amount must be a string formatted with a period as the decimal separator and up to 8 decimal places (e.g., "100.50").
  2. Sign this message string using the private key of your hot wallet to generate a signature.

3.2. Broadcast the Signed Transaction

Endpoint: POST /api/advanced/send

Request Body:

{
  "senderAddress": "Your_Hot_Wallet_Address",
  "receiverAddress": "The_User_Withdrawal_Address",
  "amount": 100.50,
  "signature": "The_signature_generated_on_your_server"
}

Success Response:

{
  "transferId": 12345,
  "status": "queued"
}

Step 4: Sweep Operations

To periodically consolidate funds from user deposit addresses into your main hot wallet (a "sweep"), you will use the same secure /api/advanced/send endpoint from Step 3.

The process is identical, with one key difference in the signing step:

  • senderAddress: The user deposit address you want to sweep funds from.
  • receiverAddress: Your main hot wallet address.
  • signature: To create the signature, you must use the PrivateKey you saved for that specific deposit address back in Step 2.1.

📚 General & Market Data API Endpoints

The following are general-purpose endpoints you can use to enrich your integration and provide real-time data to your users.

💰 Get Balance

Returns the current balance of any wallet address.

Endpoint: GET /api/advanced/balance/{walletAddress}

📈 Get Current Price

Returns the current market price of Genesis based on the last filled trade order.

Endpoint: GET /api/advanced/gns-price

📊 Get Chart Data

Provides kline (candlestick) data suitable for charting libraries like TradingView.

Endpoint: GET /api/advanced/chart-data?symbol=GNS_USDT&interval=1H&since={unix_timestamp_ms}

Supported intervals: 5m, 15m, 1H, 4H, 1D.

📜 Get Transfer History

Lists the most recent incoming and outgoing transactions for a specified wallet address.

Endpoint: GET /api/advanced/transfers/{walletAddress}?limit=20

🧱 Get Block Details

Returns detailed information for a specific block (including transfers, confirmations, etc.) by its ID or hash.

Endpoint: GET /api/advanced/block/{hashOrId}