Back to Dashboard

API Documentation v1.0

Complete reference for the GeneSYS Wallet API. Use these endpoints to manage wallets, send transactions, process payments, and configure forwarding rules programmatically.

Overview

The GeneSYS API is a RESTful JSON API. All requests and responses use application/json content type. The base URL for all endpoints is:

/api

All timestamps are returned in ISO 8601 format (UTC). Amounts are returned as strings to preserve decimal precision.

Rate Limiting

API requests are rate-limited per API key. The default limit is 60 requests per minute. Rate limit headers are included in every response:

X-RateLimit-Limit: 60 X-RateLimit-Remaining: 55 X-RateLimit-Reset: 1710500000

Authentication

The API supports two authentication methods. Choose the appropriate method based on your use case.

JWT Token (Session-based)

Used by the admin dashboard. Obtain a token by logging in through POST /api/auth/login. Include the token in the Authorization header.

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

JWT tokens expire after 15 minutes. Use the refresh token endpoint to obtain a new access token.

API Key

Used for programmatic access. Create API keys from the dashboard or via the API. Include the key in the X-API-Key header.

X-API-Key: wk_live_a1b2c3d4e5f6...

API keys can be scoped with specific permissions: read, write, payments, and admin.

Error Handling

The API uses standard HTTP status codes. Errors return a JSON body with an error field.

{ "error": "Invalid API key", "code": "AUTH_INVALID_KEY", "statusCode": 401 }

Common Status Codes

CodeMeaning
200Success
201Created successfully
400Bad request / validation error
401Unauthorized (invalid or missing credentials)
403Forbidden (insufficient permissions)
404Resource not found
429Rate limit exceeded
500Internal server error

Wallets

POST /api/wallets/master Create a new master wallet JWT / API Key

Creates a new HD master wallet. The wallet generates a mnemonic seed phrase that can be used to derive sub-wallets for both Ethereum and Tron networks.

Request Body

FieldTypeRequiredDescription
labelstringYesHuman-readable name for the wallet
networkstringYesethereum or tron

Request Example

JSON
{ "label": "Main Treasury", "network": "ethereum" }

Response Example

JSON - 201 Created
{ "id": "mw_abc123def456", "label": "Main Treasury", "network": "ethereum", "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68", "createdAt": "2025-03-15T10:30:00.000Z" }

cURL

curl -X POST /api/wallets/master \ -H "Content-Type: application/json" \ -H "X-API-Key: YOUR_API_KEY" \ -d '{"label": "Main Treasury", "network": "ethereum"}'
GET /api/wallets/master List all master wallets JWT / API Key

Returns a paginated list of all master wallets.

Query Parameters

FieldTypeDefaultDescription
pageinteger1Page number
limitinteger20Items per page (max 100)
networkstring--Filter by network

Response Example

JSON - 200 OK
{ "wallets": [ { "id": "mw_abc123def456", "label": "Main Treasury", "network": "ethereum", "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68", "subWalletCount": 12, "createdAt": "2025-03-15T10:30:00.000Z" } ], "total": 3, "page": 1, "totalPages": 1 }

cURL

curl /api/wallets/master \ -H "X-API-Key: YOUR_API_KEY"
GET /api/wallets/master/:id Get master wallet details JWT / API Key

Returns detailed information about a specific master wallet, including balance information.

Path Parameters

FieldTypeDescription
idstringMaster wallet ID

Response Example

JSON - 200 OK
{ "id": "mw_abc123def456", "label": "Main Treasury", "network": "ethereum", "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68", "balance": { "ETH": "1.5432", "USDT": "10250.00" }, "subWalletCount": 12, "createdAt": "2025-03-15T10:30:00.000Z" }

cURL

curl /api/wallets/master/mw_abc123def456 \ -H "X-API-Key: YOUR_API_KEY"
POST /api/wallets/master/:id/sub-wallets Create a sub-wallet JWT / API Key

Derives a new sub-wallet from the specified master wallet. Sub-wallets are deterministically generated using the HD wallet derivation path.

Path Parameters

FieldTypeDescription
idstringMaster wallet ID

Request Body

FieldTypeRequiredDescription
labelstringNoOptional label for the sub-wallet
metadataobjectNoCustom metadata to attach

Response Example

JSON - 201 Created
{ "id": "sw_xyz789abc012", "masterWalletId": "mw_abc123def456", "address": "0x1234567890abcdef1234567890abcdef12345678", "index": 5, "network": "ethereum", "label": "Customer Deposit #5", "createdAt": "2025-03-15T11:00:00.000Z" }

cURL

curl -X POST /api/wallets/master/mw_abc123def456/sub-wallets \ -H "Content-Type: application/json" \ -H "X-API-Key: YOUR_API_KEY" \ -d '{"label": "Customer Deposit #5"}'
GET /api/wallets/master/:id/sub-wallets List sub-wallets JWT / API Key

Returns a paginated list of sub-wallets for a given master wallet.

Path Parameters

FieldTypeDescription
idstringMaster wallet ID

Query Parameters

FieldTypeDefaultDescription
pageinteger1Page number
limitinteger20Items per page (max 100)

Response Example

JSON - 200 OK
{ "subWallets": [ { "id": "sw_xyz789abc012", "masterWalletId": "mw_abc123def456", "address": "0x1234567890abcdef1234567890abcdef12345678", "index": 0, "network": "ethereum", "label": "Customer Deposit #1", "createdAt": "2025-03-15T11:00:00.000Z" } ], "total": 12, "page": 1, "totalPages": 1 }

cURL

curl /api/wallets/master/mw_abc123def456/sub-wallets?page=1&limit=20 \ -H "X-API-Key: YOUR_API_KEY"
GET /api/wallets/sub/:id/balance Get sub-wallet balance JWT / API Key

Returns the current balance of a specific sub-wallet, including native token and USDT balances.

Path Parameters

FieldTypeDescription
idstringSub-wallet ID

Response Example

JSON - 200 OK
{ "id": "sw_xyz789abc012", "address": "0x1234567890abcdef1234567890abcdef12345678", "network": "ethereum", "balances": { "ETH": "0.05432", "USDT": "125.50" }, "lastUpdated": "2025-03-15T12:00:00.000Z" }

cURL

curl /api/wallets/sub/sw_xyz789abc012/balance \ -H "X-API-Key: YOUR_API_KEY"

Transactions

GET /api/transactions List transactions JWT / API Key

Returns a paginated, filterable list of all transactions across wallets.

Query Parameters

FieldTypeDefaultDescription
pageinteger1Page number
limitinteger20Items per page
networkstring--Filter by network (ethereum, tron)
statusstring--Filter by status (pending, confirmed, failed)
tx_typestring--Filter by type (deposit, withdrawal, forward, sweep)
walletIdstring--Filter by wallet ID

Response Example

JSON - 200 OK
{ "transactions": [ { "id": "tx_abc123", "txHash": "0xabc123...", "network": "ethereum", "type": "deposit", "status": "confirmed", "from": "0xsender...", "to": "0xreceiver...", "amount": "0.5", "token": "ETH", "confirmations": 12, "createdAt": "2025-03-15T10:00:00.000Z" } ], "total": 156, "page": 1, "totalPages": 8 }

cURL

curl "/api/transactions?network=ethereum&status=confirmed&page=1" \ -H "X-API-Key: YOUR_API_KEY"
POST /api/transactions/send Send a transaction JWT / API Key (write)

Initiates an outgoing transaction from a specified wallet. The transaction is signed server-side and broadcast to the blockchain network.

Request Body

FieldTypeRequiredDescription
fromWalletIdstringYesSource wallet ID (master or sub)
tostringYesDestination address
amountstringYesAmount to send
tokenstringNoToken symbol (default: native token). Use USDT for stablecoin transfers.
networkstringYesethereum or tron

Request Example

JSON
{ "fromWalletId": "mw_abc123def456", "to": "0x9876543210fedcba9876543210fedcba98765432", "amount": "0.5", "token": "ETH", "network": "ethereum" }

Response Example

JSON - 201 Created
{ "id": "tx_def456", "txHash": "0xdef456...", "status": "pending", "network": "ethereum", "from": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68", "to": "0x9876543210fedcba9876543210fedcba98765432", "amount": "0.5", "token": "ETH", "createdAt": "2025-03-15T12:30:00.000Z" }

cURL

curl -X POST /api/transactions/send \ -H "Content-Type: application/json" \ -H "X-API-Key: YOUR_API_KEY" \ -d '{ "fromWalletId": "mw_abc123def456", "to": "0x9876543210fedcba9876543210fedcba98765432", "amount": "0.5", "token": "ETH", "network": "ethereum" }'

Payments

POST /api/payments/create Create a payment request JWT / API Key (payments)

Creates a new payment request. This generates a unique deposit address where the payer should send funds. The system monitors the address and triggers webhook notifications on status changes.

Request Body

FieldTypeRequiredDescription
networkstringYesethereum or tron
tokenstringYesETH, TRX, or USDT
amountnumberYesExpected payment amount
callbackUrlstringNoWebhook URL for status notifications
metadataobjectNoCustom metadata (e.g., order ID)

Request Example

JSON
{ "network": "ethereum", "token": "USDT", "amount": 100.00, "callbackUrl": "https://your-server.com/webhook/payment", "metadata": { "orderId": "ORD-12345", "customer": "john@example.com" } }

Response Example

JSON - 201 Created
{ "payment": { "paymentId": "pay_a1b2c3d4e5", "status": "pending", "network": "ethereum", "token": "USDT", "expectedAmount": "100.00", "receivedAmount": "0", "depositAddress": "0xunique_deposit_address_here", "expiresAt": "2025-03-15T22:30:00.000Z", "metadata": {"orderId": "ORD-12345"}, "createdAt": "2025-03-15T10:30:00.000Z" } }

cURL

curl -X POST /api/payments/create \ -H "Content-Type: application/json" \ -H "X-API-Key: YOUR_API_KEY" \ -d '{ "network": "ethereum", "token": "USDT", "amount": 100.00, "callbackUrl": "https://your-server.com/webhook/payment" }'
GET /api/payments/:paymentId Get payment details JWT / API Key

Returns complete details for a specific payment, including the current status, received amount, and associated transactions.

Path Parameters

FieldTypeDescription
paymentIdstringPayment ID returned from creation

Response Example

JSON - 200 OK
{ "payment": { "paymentId": "pay_a1b2c3d4e5", "status": "completed", "network": "ethereum", "token": "USDT", "expectedAmount": "100.00", "receivedAmount": "100.00", "depositAddress": "0xunique_deposit_address_here", "transactions": [ { "txHash": "0xabc...", "amount": "100.00", "confirmations": 15, "confirmedAt": "2025-03-15T11:15:00.000Z" } ], "expiresAt": "2025-03-15T22:30:00.000Z", "completedAt": "2025-03-15T11:15:00.000Z", "metadata": {"orderId": "ORD-12345"}, "createdAt": "2025-03-15T10:30:00.000Z" } }

cURL

curl /api/payments/pay_a1b2c3d4e5 \ -H "X-API-Key: YOUR_API_KEY"
POST /api/payments/:paymentId/check Force check payment status JWT / API Key

Triggers an immediate check of the payment's deposit address for incoming transactions. Useful for forcing a status update without waiting for the automatic polling interval.

Path Parameters

FieldTypeDescription
paymentIdstringPayment ID to check

Response Example

JSON - 200 OK
{ "paymentId": "pay_a1b2c3d4e5", "status": "completed", "previousStatus": "pending", "receivedAmount": "100.00", "checkedAt": "2025-03-15T12:00:00.000Z" }

cURL

curl -X POST /api/payments/pay_a1b2c3d4e5/check \ -H "X-API-Key: YOUR_API_KEY"

Try It

Test API endpoints directly from your terminal. Replace YOUR_API_KEY with your actual key.

Quick Start

1. Create an API key from the API Keys page.

2. Copy one of the cURL examples above.

3. Replace YOUR_API_KEY with your key.

4. Run the command in your terminal.

Example: List Your Wallets

curl -s http://localhost:3000/api/wallets/master \ -H "X-API-Key: wk_live_YOUR_KEY_HERE" | json_pp

Example: Create a Payment

curl -s -X POST http://localhost:3000/api/payments/create \ -H "Content-Type: application/json" \ -H "X-API-Key: wk_live_YOUR_KEY_HERE" \ -d '{"network":"ethereum","token":"USDT","amount":50}' | json_pp

Example: Check a Transaction

curl -s "http://localhost:3000/api/transactions?status=pending&limit=5" \ -H "X-API-Key: wk_live_YOUR_KEY_HERE" | json_pp