API Documentation

Etherly Reseller API allows you to programmatically generate VPN activation codes, manage your reseller balance, and integrate Etherly into your own services.

Base URL: https://api.etherly.one/api/reseller

Quick Start

Register at reseller.etherly.one
Activate your reseller account in the dashboard
Copy your API key from the dashboard
Top up your balance with crypto (minimum $10)
Start generating activation codes via API

Authentication

All API requests must include your API key in the x-api-key header. You can find your API key in the reseller dashboard.

bash

curl -X GET https://api.etherly.one/api/reseller/me \
  -H "x-api-key: your-api-key-here"

Note: You can also authenticate using the x-seed-hash header (same as the web dashboard). API key authentication is recommended for programmatic access.

Get Plans

GET/plans

Returns all available VPN plans with retail and wholesale pricing. No authentication required.

Response

json

[
  {
    "id": "1month",
    "name": "1 Month",
    "days": 30,
    "retailPrice": 1.99,
    "wholesalePrice": 1.00,
    "margin": 0.99
  },
  {
    "id": "6month",
    "name": "6 Months",
    "days": 180,
    "retailPrice": 9.99,
    "wholesalePrice": 5.00,
    "margin": 4.99
  },
  {
    "id": "12month",
    "name": "12 Months",
    "days": 365,
    "retailPrice": 19.99,
    "wholesalePrice": 10.00,
    "margin": 9.99
  }
]

Get Profile

GET/me

Returns your reseller profile including balance, API key, and sales statistics.

Response

json

{
  "companyName": "MyBrand",
  "balance": 45.00,
  "status": "active",
  "apiKey": "a1b2c3d4e5f6...",
  "stats": {
    "totalCodes": 120,
    "redeemedCodes": 87,
    "totalTopups": 250.00
  }
}

bash

curl -X GET https://api.etherly.one/api/reseller/me \
  -H "x-api-key: your-api-key"

Generate Codes

POST/generate

Generate VPN activation codes. The cost is deducted from your balance at wholesale prices. Each code is a unique link that customers can use to activate their subscription.

Name

Name	Type	Description
`planId`*	string	Plan identifier: 1month, 6month, or 12month
`count`	number	Number of codes to generate (1-100, default: 1)

Request Body

json

{
  "planId": "6month",
  "count": 5
}

Response

json

{
  "ok": true,
  "codes": [
    {
      "code": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
      "url": "https://etherly.one/activate/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
    }
  ],
  "totalCost": 25.00,
  "newBalance": 20.00
}

bash

curl -X POST https://api.etherly.one/api/reseller/generate \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"planId": "6month", "count": 5}'

Activation flow: Share the url with your customer. They visit the link, create an Etherly account (or log in), and click activate. The VPN subscription is instantly applied to their account.

List Codes

GET/codes

List all activation codes you have generated, with filtering and pagination.

Name

Name	Type	Description
`page`	number	Page number (default: 1)
`status`	string	Filter: available or redeemed (omit for all)

Response

json

{
  "codes": [
    {
      "code": "a1b2c3d4...",
      "plan_id": "6month",
      "days": 180,
      "redeemed_by": null,
      "redeemed_at": null,
      "created_at": "2026-03-22T10:30:00.000Z"
    }
  ],
  "total": 45,
  "page": 1,
  "pages": 1
}

bash

curl -X GET "https://api.etherly.one/api/reseller/codes?page=1&status=available" \
  -H "x-api-key: your-api-key"

Top Up Balance

POST/topup

Create a crypto payment to top up your reseller balance. Minimum amount is $10. Returns a payment URL where you complete the transaction.

Name

Name	Type	Description
`amount`*	number	Amount in USD (minimum 10)

Request Body

json

{
  "amount": 50
}

Response

json

{
  "ok": true,
  "paymentUrl": "https://pay.heleket.com/...",
  "orderId": "reseller_topup_1_1711100000"
}

Payment flow: Open the paymentUrl to complete the crypto payment. Once confirmed, your balance is automatically updated. Poll the /topup/status/:orderId endpoint to check status.

Top Up Webhook

POST/topup/webhook

Webhook endpoint called by the payment provider when a top-up payment is confirmed. You do not need to call this endpoint — it is handled automatically.

Response

json

{
  "ok": true
}

Top Up Status

GET/topup/status/:orderId

Check the status of a top-up payment. Poll this endpoint after creating a top-up to know when the payment is confirmed.

Name

Name	Type	Description
`orderId`*	string	The orderId returned from the /topup endpoint

Response

json

{
  "status": "confirmed",
  "amount": 50.00,
  "balance": 95.00
}

bash

curl -X GET https://api.etherly.one/api/reseller/topup/status/reseller_topup_1_1711100000

Regenerate Key

POST/regenerate-key

Generate a new API key. The old key is immediately invalidated. Make sure to update your integrations with the new key.

Response

json

{
  "ok": true,
  "apiKey": "new-64-char-hex-api-key..."
}

bash

curl -X POST https://api.etherly.one/api/reseller/regenerate-key \
  -H "x-api-key: your-current-api-key"

Webhooks

Etherly uses webhooks for payment confirmation. The top-up webhook is handled internally — you do not need to set up any webhook endpoints on your side.

To track code redemptions, poll the /codes endpoint periodically and check the redeemed_by field.

Error Handling

All errors return a JSON object with an error field.

json

{
  "error": "Insufficient balance",
  "required": 25.00,
  "balance": 10.00
}

HTTP Status Codes

Code	Description
200	Success
400	Bad request — invalid parameters or insufficient balance
401	Unauthorized — missing or invalid API key
403	Forbidden — account suspended
404	Not found
429	Rate limited — too many requests
500	Internal server error
503	Payment service not configured

Rate Limits

Endpoint	Limit
/register	20 requests / 15 minutes
/generate	No specific limit (balance-gated)
/codes	No specific limit
/topup	10 requests / 15 minutes
All other endpoints	Standard rate limiting applies

Need help? Contact us at etherly.one/support