API Documentation

Use your personal API key (created under API Keys) to generate wallets, list your wallets, and read transaction history programmatically.

Base URL

https://api.gen-wallet.space/api/v1

Authentication

Every request must include your API key in the x-api-key header.

curl https://api.gen-wallet.space/api/v1/wallets \
  -H "x-api-key: YOUR_API_KEY"

IP allowlist — set in API Key settings. Use 0.0.0.0 to allow all IPs, or a comma-separated list of allowed IPs.
Permissions — each key can be granted GenerateAddress (create wallets), DataList (read wallets/balances/transactions), and Withdraw (send GRAM (TON)/USDT from your wallets).
Status — a key with status disabled will reject all requests.
Wallet limit — your account may have a maximum number of wallets you can generate, set by the dashboard owner.

Endpoints

GET/wallets

List wallets generated by your account. Supports search and pagination.

Required permission: DataList

Query parameters

search   (optional) — match address or label
page     (optional, default 1)
pageSize (optional, default 20, max 100)

Example response

{
  "wallets": [
    {
      "id": "clx123...",
      "label": "user-1042",
      "address": "UQ...",
      "publicKey": "ab12...",
      "walletVersion": "v5r1",
      "network": "mainnet",
      "createdAt": "2026-06-01T12:00:00.000Z"
    }
  ],
  "pagination": { "page": 1, "pageSize": 20, "total": 1, "totalPages": 1 }
}

POST/wallets

Generate a new GRAM (TON) wallet for your account. The recovery phrase is NOT returned via the API — only the dashboard owner can reveal it.

Required permission: GenerateAddress

Body

{
  "label": "optional-label"
}

Example response

{
  "wallet": {
    "id": "clx456...",
    "label": "optional-label",
    "address": "UQ...",
    "publicKey": "cd34...",
    "walletVersion": "v5r1",
    "network": "mainnet",
    "createdAt": "2026-06-12T10:00:00.000Z"
  }
}

GET/wallets/:address/transactions

Get synced transaction history for one of your wallets, identified by its address.

Required permission: DataList

Query parameters

page     (optional, default 1)
pageSize (optional, default 20, max 100)

Example response

{
  "address": "UQ...",
  "transactions": [
    {
      "txHash": "ab12...",
      "lt": "123456000001",
      "utime": 1750000000,
      "direction": "in",
      "amountNano": "1000000000",
      "feeNano": "1000000",
      "fromAddress": "UQ...",
      "toAddress": "UQ...",
      "comment": null,
      "createdAt": "2026-06-12T10:05:00.000Z"
    }
  ],
  "pagination": { "page": 1, "pageSize": 20, "total": 1, "totalPages": 1 }
}

GET/wallets/:address

Get info and live balance for a single wallet, identified by its address.

Required permission: DataList

Example response

{
  "id": "clx123...",
  "label": "user-1042",
  "address": "UQ...",
  "publicKey": "ab12...",
  "walletVersion": "v5r1",
  "network": "mainnet",
  "createdAt": "2026-06-01T12:00:00.000Z",
  "balanceNano": "1500000000",
  "balanceTon": 1.5,
  "usdtBalanceRaw": "2500000",
  "usdtBalance": 2.5
}

GET/wallets

Get the list of your wallets filtered by an exact label match.

Required permission: DataList

Query parameters

label    (required) — exact label to match
page     (optional, default 1)
pageSize (optional, default 20, max 100)

Example response

{
  "wallets": [
    {
      "id": "clx123...",
      "label": "user-1042",
      "address": "UQ...",
      "publicKey": "ab12...",
      "walletVersion": "v5r1",
      "network": "mainnet",
      "createdAt": "2026-06-01T12:00:00.000Z"
    }
  ],
  "pagination": { "page": 1, "pageSize": 20, "total": 1, "totalPages": 1 }
}

GET/balance

Get the combined GRAM (TON)/USDT balance across all of your wallets.

Required permission: DataList

Example response

{
  "walletCount": 4,
  "totalTon": 12.345,
  "totalUsdt": 100.5
}

GET/transactions

Get synced transaction history across all of your wallets, newest first.

Required permission: DataList

Query parameters

limit  (optional, default 20, max 100)
offset (optional, default 0)

Example response

{
  "transactions": [
    {
      "address": "UQ...",
      "txHash": "ab12...",
      "lt": "123456000001",
      "utime": 1750000000,
      "direction": "in",
      "amountNano": "1000000000",
      "feeNano": "1000000",
      "fromAddress": "UQ...",
      "toAddress": "UQ...",
      "comment": null,
      "createdAt": "2026-06-12T10:05:00.000Z"
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "total": 1 }
}

POST/wallets/:address/withdraw

Withdraw GRAM (TON) or USDT from one of your wallets to any GRAM (TON) address.

Required permission: Withdraw

Body

{
  "token": "GRAM"// "GRAM" | "USDT",       // "TON" | "USDT"
  "toAddress": "UQ...",
  "amount": "1.5",
  "comment": "optional"
}

Example response

{
  "ok": true,
  "seqno": 12345
}

Errors

Errors are returned as JSON with an HTTP status code:

{ "error": "Invalid API key" }      // 401
{ "error": "IP not allowed" }       // 403
{ "error": "Wallet limit reached (10). Contact the administrator to increase it." } // 403
{ "error": "Wallet not found" }     // 404

Webhooks (optional)

If Webhook Active is enabled on your API key, a POST request will be sent to your Webhook Url when relevant deposit/withdraw events occur on your wallets. Configure this from the Edit Api page.