System Bootstrap

Flow Summary

The current system-bootstrap flow is:

Step 1. Generate an encryption key pair
POST /api/v1/sys/key-pair

Step 2. Load supported blockchain networks
GET /api/v1/sys/networks

Both routes are public and do not require Authorization.

1. When To Use This Module

Use these endpoints during app bootstrap when you need to:

• start the optional encrypted-request handshake before sending sensitive JSON payloads
• display which blockchain deposit or settlement networks the mobile app currently supports

2. Generate Encryption Key Pair

POST /api/v1/sys/key-pair

Send the mobile client public key so the server can generate a temporary server key pair for encrypted request exchange.

Request body

{
  "key": "base64-encoded-32-byte-client-public-key"
}

Validation rules

• key is required
• the value must be valid Base64
• after Base64 decode, the key must be exactly 32 bytes

Success response

{
  "status_code": 200,
  "message": "Success",
  "data": {
    "server_pub_key": [12, 44, 91, 7],
    "key_version": "f7e7a0be-1742-4d8c-9c7d-bf32f23f88c1"
  }
}

Important backend behavior

• server_pub_key is returned as a JSON array of 32 integers, not a Base64 string
• key_version is returned as a UUID string; send this raw value back later in the encrypted wrapper
• the server stores the key pair in Redis for 30 minutes
• internally the Redis key uses MD5(key_version), but clients should keep using the original key_version
• this route passes through DecryptField() middleware, but bootstrap requests normally use plain JSON because this call creates the first key pair

Error caveat

• invalid client keys return a logical 400 error
• the error message text is specific, but the locale key used by the service is still the generic internal-server-error translation

3. Get Supported Networks

GET /api/v1/sys/networks

Returns the blockchain networks currently exposed to the mobile app.

Success response

{
  "status_code": 200,
  "message": "Success",
  "data": {
    "networks": [
      {
        "name": "Tron (TRC20)",
        "code": "TRC20"
      }
    ],
    "description": "Supports Tron (TRC20) network only"
  }
}

Important backend behavior

• the current backend returns only one network: TRC20
• the network name and code are fixed values from the enum layer
• only the description field is localized
• if translation fails, the handler falls back to the hardcoded English text Supports Tron (TRC20) network only

Integration Notes

1. Call POST /api/v1/sys/key-pair only when the client really needs encrypted request payloads.
2. Re-bootstrap the key pair if the client waits longer than 30 minutes before sending the encrypted request.
3. Treat GET /api/v1/sys/networks as the source of truth for supported network options instead of hardcoding future assumptions.