Wallet API Overview

📖

Read Operations

Use /query endpoint for all read-only operations like listing accounts and getting profile details

✏️

Write Operations

Use /command endpoint for all write/mutate operations like creating investments and updating profiles

🔐

Secure Authentication

All requests require Bearer token with a signature generated by a private key that MUST never leave your infrastructure.

Authentication

API Key Setup

  1. Login to wallet.halogen.my
  2. Navigate to Settings → API Keys
  3. Create a new API key by providing a Certificate Signing Request (CSR)
  4. Supported algorithms: Elliptic Curve P-256 RSA-4096

Generate CSR

Elliptic Curve P-256 
mkdir -p .key
openssl ecparam -name prime256v1 -genkey -noout -out .key/ec_private_key.pem
openssl req -new -key .key/ec_private_key.pem -out .key/ec_csr.pem -sha256 \
  -subj "/C=MY/ST=State/L=City/O=Organization/OU=Unit/CN=example.com"
RSA-4096 
mkdir -p .key
openssl req -new -newkey rsa:4096 -nodes -keyout .key/rsa_private_key.pem -out .key/rsa_csr.pem \
  -subj "/C=MY/ST=State/L=City/O=Organization/OU=Unit/CN=example.com"
⚠️ Security Note: Keep your private key secure and never share it. This key is used to digitally sign your API requests.

API Endpoints

POST
/query
Read Only

Execute read-only operations to retrieve data from the API

Request Body 
{
  "name": "list_client_accounts",
  "payload": {
    "accountIds": ["account_123", "account_456"]
  }
}
cURL Example 
curl -X POST https://external-api.wallet.halogen.my/query \
  -H "Authorization: Bearer {JWT}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "list_client_accounts",
    "payload": {
      "accountIds": ["account_123"]
    }
  }'
200 OK Successful Response
Response Body 
{
  "amount": 150000.50,
  "asset": "MYR",
  "canCreateAccount": true,
  "accounts": [
    {
      "id": "account_123",
      "type": "single",
      "name": "Investment Account",
      "experience": "fundmanagement",
      "portfolioValue": 75000.25,
      "exposurePercentage": 50.0,
      "canInvest": true,
      "canRedeem": true
    }
  ]
}

Error Responses

400 Bad Request - Invalid parameters
401 Unauthorized - Invalid or missing API token
403 Forbidden - Insufficient access
404 Not Found - Resource does not exist
429 Too Many Requests - Rate limit exceeded
POST
/command
Write

Execute write/mutate operations to modify data in the API

Request Body 
{
  "name": "create_investment_request",
  "payload": {
    "accountId": "account_123",
    "amount": 10000.00
  }
}
cURL Example 
curl -X POST https://external-api.wallet.halogen.my/command \
  -H "Authorization: Bearer {JWT}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "create_investment_request",
    "payload": {
      "accountId": "account_123",
      "amount": 10000.00
    }
  }'
200 OK Successful Response
Response Body 
{
  "requestId": "req_abc123xyz789"
}

Error Responses

400 Bad Request - Invalid parameters or insufficient balance
401 Unauthorized - Invalid or missing API token
403 Forbidden - Insufficient access
412 Precondition Failed - Action not allowed for account type
429 Too Many Requests - Rate limit exceeded