Setup Auto Top-Up

This endpoint programmatically generates a cryptocurrency wallet address and calculates the required payment amount to auto-top-up the user's Dataoorts account balance. It is used to automate account recharges using supported crypto currencies and blockchain networks.

Generate a Cryptocurrency Payment Address

The Dataoorts Auto Top-Up API enables developers to programmatically generate a cryptocurrency payment address for adding funds to their Dataoorts account.

By integrating this endpoint with a supported cryptocurrency payment provider, you can automate your account recharge workflow without manually generating a payment address through the dashboard.

When a payment address is successfully generated, the API returns the deposit address, the requested recharge amount, the exact cryptocurrency amount to pay, and a unique order ID. Once the blockchain transaction is confirmed and processed by Dataoorts, the eligible recharge amount is automatically credited to your account balance, and an email notification is sent.

Payment method availability: Automatic payments currently support cryptocurrency only, Card and UPI support may be introduced in the future.

Auto-Payment Endpoint

Property	Value
HTTP Method	POST
Endpoint	/billing/crypto/address
Full URL	https://cloud.dataoorts.com/api/v1/billing/crypto/address
Authentication	Bearer Token
Content Type	application/json
Success Status	201 Created
Rate Limit	Up to 5 requests per minute

Authentication

This endpoint requires a valid Dataoorts Unify API key.

Include your API key in the Authorization header using the Bearer authentication scheme.

HTTP

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json

You can generate or manage your API key through the Dataoorts Unify API.

Keep your API key confidential and never expose it in public repositories or client-side applications.

Request Parameters

The request body must be sent as JSON.

Parameter	Type	Required	Description
amount_usd	Number	Yes	The requested recharge amount in USD, before the cryptocurrency gateway processing fee.
crypto_currency	String	Yes	The cryptocurrency ticker, such as USDT, LTC, or BTC.
network	String	Yes	The blockchain network to use, such as tron, bsc, polygon, or eth.

Important: Ensure the selected cryptocurrency and blockchain network combination is supported. Supported combinations may vary; an invalid or unsupported combination can result in an address generation error.

Cryptocurrency Gateway Fee

A standard 1.95% cryptocurrency gateway processing fee is applied to the requested recharge amount.

The total payment amount is calculated as follows: Total Payment = Requested Amount × 1.0195

For example, if you request a recharge of $100.00, the applicable processing fee is $1.95, making the total amount payable $101.95 in the equivalent cryptocurrency.

The API returns the exact cryptocurrency payment amount in the exact_crypto_amount_to_pay field, Always use this returned value when initiating the transfer.

Request Examples

Generate a cryptocurrency payment address using cURL:

Bash

curl --request POST \
  --url "https://cloud.dataoorts.com/api/v1/billing/crypto/address" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "amount_usd": 100.00,
    "crypto_currency": "USDT",
    "network": "bsc"
  }'

Replace YOUR_API_KEY with your actual Dataoorts Unify API key. You can change the amount, cryptocurrency, and network according to your requirements and the combinations supported by the API.

The following example uses the requests library to generate a cryptocurrency payment address and retrieve the payment details.

Python Example implementation:

Python

import os
import requests


API_URL = (
    "https://cloud.dataoorts.com"
    "/api/v1/billing/crypto/address"
)


def generate_crypto_payment_address(
    api_key: str,
    amount_usd: float,
    crypto_currency: str = "USDT",
    network: str = "bsc",
) -> dict:
    """
    Generate a cryptocurrency payment address for Dataoorts.

    Args:
        api_key: Your Dataoorts Unify API key.
        amount_usd: Requested account recharge amount in USD.
        crypto_currency: Cryptocurrency ticker, e.g. USDT.
        network: Blockchain network, e.g. bsc.

    Returns:
        dict: The JSON response containing payment details.

    Raises:
        requests.exceptions.RequestException:
            If the HTTP request fails or returns an unsuccessful
            HTTP status code.
        ValueError:
            If the response is not valid JSON.
    """
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
        "Accept": "application/json",
    }

    payload = {
        "amount_usd": amount_usd,
        "crypto_currency": crypto_currency,
        "network": network,
    }

    response = requests.post(
        API_URL,
        headers=headers,
        json=payload,
        timeout=30,
    )

    response.raise_for_status()
    return response.json()


if __name__ == "__main__":
    api_key = os.getenv("DATAOORTS_API_KEY")

    if not api_key:
        raise RuntimeError(
            "Set the DATAOORTS_API_KEY environment variable."
        )

    try:
        result = generate_crypto_payment_address(
            api_key=api_key,
            amount_usd=100.00,
            crypto_currency="USDT",
            network="bsc",
        )

        if result.get("status") == "success":
            payment = result.get("data", {})

            print("Payment address:", payment.get("address"))
            print("Currency:", payment.get("currency"))
            print("Network:", payment.get("network"))
            print(
                "Exact amount to pay:",
                payment.get("exact_crypto_amount_to_pay"),
            )
            print("Order ID:", payment.get("order_id"))
            print(
                "Address valid for 50 minutes. "
                "Complete the transfer before expiry."
            )
        else:
            print("API error:", result.get("message", "Unknown error"))

    except requests.exceptions.RequestException as exc:
        print(f"HTTP request failed: {exc}.")

    except ValueError as exc:
        print(f"Invalid JSON response: {exc}.")

Set your Unify API key before running the script.

Linux / macOS

Bash

export DATAOORTS_API_KEY="YOUR_API_KEY"
python auto_topup.py

Windows PowerShell

PowerShell

$env:DATAOORTS_API_KEY="YOUR_API_KEY"
python auto_topup.py

The example generates a payment address and displays the payment details. It does not independently initiate a cryptocurrency transfer; that step requires a supported external payment provider or wallet integration.

Example Success Response

HTTP Status: 201 Created

When the payment address is generated successfully, the API returns a JSON response containing the deposit address and payment details.

JSON

{
  "status": "success",
  "message": "Payment address generated successfully.",
  "data": {
    "base_amount_usd": 1000.0,
    "address": "TXYZ1234567890abcdefghijklmnopqrstuvwxyz",
    "exact_crypto_amount_to_pay": "1019.5",
    "currency": "USDT",
    "network": "bsc",
    "order_id": 45612341525112023,
    "note": "Payment variations are acceptable, The system is flexible."
  }
}

The address and order ID above are illustrative examples, Successful API response returns the actual payment details for your request.

Response Fields

Field	Type	Description
status	String	Indicates the result of the request. A successful response returns success.
message	String	A descriptive message confirming that the payment address was generated.
data.base_amount_usd	Number	The requested recharge amount in USD, excluding the gateway processing fee.
data.address	String	The cryptocurrency deposit address generated for the payment session.
data.exact_crypto_amount_to_pay	String	The exact cryptocurrency amount to transfer, including the applicable gateway fee.
data.currency	String	The cryptocurrency associated with the payment address.
data.network	String	The blockchain network associated with the payment address.
data.order_id	Number	The unique identifier associated with the payment order.
data.note	String	Additional information about the payment, if provided by the API.

Error Responses

If the request cannot be completed, the API returns an error response with an appropriate HTTP status code and a JSON body describing the issue.

400 Bad Request — Invalid or Low Recharge Amount

Returned when the requested recharge amount does not meet the minimum allowed amount.

JSON

{
  "status": "error",
  "message": "Minimum recharge amount is $4.5 USD."
}

Resolution: Increase amount_usd to meet the minimum recharge requirement.

401 Unauthorized — Missing or Invalid Authorization Format

Returned when the Authorization header is missing or does not use the required Bearer token format.

JSON

{
  "status": "error",
  "message": "Authorization header with 'Bearer <TOKEN>' is required."
}

Resolution: Provide the API key using the Authorization: Bearer YOUR_API_KEY header.

403 Forbidden — Invalid API Key

Returned when the supplied API key is invalid or unauthorized.

JSON

{
  "status": "error",
  "message": "Unauthorized: Invalid API key."
}

Resolution: Verify that you are using a valid Dataoorts Unify API key.

502 Bad Gateway — Unsupported Currency or Network

Returned when server cannot generate payment address for requested cryptocurrency & network combination.

JSON

{
  "status": "error",
  "message": "Server failed to generate address, Invalid currency or network."
}

Resolution: Verify the crypto_currency and network values and use a supported combination.

Payment Workflow

The automated top-up process consists of the following steps:

1. Generate a payment address: Send a POST request with recharge amount, cryptocurrency, and network.
2. Retrieve payment details: Read the returned address, exact_crypto_amount_to_pay, currency, network, and order_id.
3. Initiate the transfer: Use a supported cryptocurrency provider or wallet to transfer funds to the returned address on the specified blockchain network.
4. Wait for blockchain confirmation: Dataoorts processes the payment after the transaction is confirmed and accepted by its payment system.
5. Receive account credit: The eligible recharge amount is automatically credited to your Dataoorts account balance, and an email notification is sent.

Important Payment Requirements

1. Transfer the Exact Amount

Always use the value returned in exact_crypto_amount_to_pay when initiating your transfer, Payment system accommodate certain payment variations and adjust the credited balance according to the amount received.

2. Payment Address Expiration

Each generated payment address is valid for 50 minutes. Complete the transfer within the validity period. Do not send funds to an expired payment address, as late or unconfirmed transactions may not be processed as expected and could result in financial loss.

3. Automatic Balance Credit

You do not need to manually refresh the payment status to trigger a recharge. Once the blockchain transaction is confirmed and successfully processed by Dataoorts, the eligible recharge amount is automatically credited to your account balance and an email notification is sent. Allow time for blockchain confirmations and payment processing. Generating an address alone does not mean the account has been credited.

4. Locked Cryptocurrency Exchange Rate

Cryptocurrency exchange rates may fluctuate. To protect against subsequent price changes, the applicable crypto-to-USD conversion rate is locked at the time the payment address is generated. Use the returned payment amount and complete the payment within the address's validity period.

5. API Rate Limits

This endpoint allows up to 5 payment address generation requests per minute. Avoid generating unnecessary addresses. Integrations should handle errors appropriately and respect the endpoint's rate limit.

6. Supported Payment Methods

Automatic top-up currently supports cryptocurrency payments only. Card and UPI automatic payments are not currently supported through this workflow.

7. Blockchain Network Compatibility

Always transfer the cryptocurrency using the exact network specified in the API response. Sending funds through an incompatible network or to an incorrect address may result in an unsuccessful/irreversible transfer.

Get Billing Support

For assistance with automatic top-up, payment address generation, or API integration, contact the Dataoorts support team at [email protected].