Bailian Balance Query Adapter

A local HTTP adapter for querying Alibaba Cloud (Aliyun) account balance via BSS OpenAPI.
Runs as a local web service, accepts Aliyun AccessKey credentials via Authorization header, and returns real-time account balance.

Features

• Zero config - start the server, send your credentials per request
• No credential storage - AccessKeys are passed per-request via HTTP header, never persisted
• Single endpoint - GET /api/balance with Authorization header
• Aliyun BSS API - uses official Alibaba Cloud SDK for HMAC-SHA1 signed requests
• Background daemon - built-in daemon mode with process management

Quick Start

# Install globally
npm install -g bailian-balance-query-adapter

# Start as background daemon
bailian-balance-adapter daemon

# Server starts at http://localhost:3456

CLI Commands

bailian-balance-adapter <command>

Commands:
  start             Start server in foreground (Ctrl+C to stop)
  daemon            Start server as background daemon
  stop              Stop the background daemon
  restart           Restart the background daemon
  status            Show daemon status
  logs              Stream daemon logs (Ctrl+C to exit)

Or via npm scripts:

npm start          # foreground
npm run daemon     # background
npm run stop       # stop daemon
npm run restart    # restart daemon
npm run status     # check status
npm run logs       # stream logs

Usage

# Query balance with your Aliyun AccessKey
AK_ID="your-access-key-id"
AK_SECRET="your-access-key-secret"
AUTH=$(echo -n "${AK_ID}:${AK_SECRET}" | base64)

curl -H "Authorization: ALIYUN ${AUTH}" http://localhost:3456/api/balance

Response

{
  "code": 200,
  "success": true,
  "data": {
    "availableAmount": "100.00",
    "creditAmount": "0.00",
    "currency": "CNY",
    "availableCashAmount": "100.00",
    "mybankCreditAmount": "0.00",
    "requestId": "2F7A60C9-1B6C-4E6B-AE30-BB8A2F4E5C20"
  }
}

API

GET /api/balance

Query Alibaba Cloud account balance.

Headers

| Header | Value | |--------|-------| | Authorization | ALIYUN <base64(AccessKeyId:AccessKeySecret)> |

Response

| Field | Type | Description | |-------|------|-------------| | code | int | HTTP status code | | success | bool | Request success | | data.availableAmount | string | Available balance (CNY) | | data.creditAmount | string | Credit amount | | data.currency | string | Currency code | | data.availableCashAmount | string | Available cash balance | | data.mybankCreditAmount | string | Mybank credit amount | | data.requestId | string | Aliyun API request ID |

GET /health

Health check endpoint.

Authorization Header

ALIYUN <base64-encoded "AccessKeyId:AccessKeySecret">

Example:

echo -n "LTAI5tAKID123456:AKSecretYourKeyHere" | base64
# Output: TFRBSTRBS0lEMTIzNDU2OkFLU2VjcmV0WW91cktleUhlcmU=

curl -H "Authorization: ALIYUN TFRBSTRBS0lEMTIzNDU2OkFLU2VjcmV0WW91cktleUhlcmU=" \
  http://localhost:3456/api/balance

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | PORT | 3456 | HTTP server port |

Architecture

Client ── HTTP ──▶ Express Server (localhost:3456)
                    │
                    ├── Auth Middleware (parse ALIYUN <base64>)
                    │
                    └── Aliyun Service (@alicloud/pop-core)
                         │
                         └── Aliyun BSS API (business.aliyuncs.com)
                              └── QueryAccountBalance

Programmatic Usage

const app = require('bailian-balance-query-adapter');

app.listen(3456, () => {
  console.log('Adapter started');
});

License

MIT

Author

zexuan.peng