A native CLIProxyAPI plugin that reads static AI providers from the CPA Management API and tracks balances for providers selected as Sub2API instances. It does not modify CPA.
- Reads Base URL and API Key entries from seven CPA static provider types.
- Lets the user select only the providers backed by Sub2API.
- Queries
GET <base-url>/v1/usage, handles wallet, quota-limited, subscription, zero-balance, and unlimited responses, and preserves quota, rate-limit, token, cost, daily-usage, and model statistics. - Configures daily-detail days, the model-statistics date range, and the daily-statistics timezone, preserving each probe's query range in history.
- Supplements usage with
GET <base-url>/v1/sub2api/billingto show token group, user, effective, and peak multipliers plus the peak billing window and timezone; billing unavailability does not fail a balance refresh. - Refreshes one provider or all selected providers with configurable concurrency and timeout.
- Supports per-provider and global HTTP, HTTPS, SOCKS5, and SOCKS5H proxies.
- Optionally refreshes balances on a fixed delay, defaulting to 60 minutes.
- Saves provider selections immediately and separates monitoring from provider configuration with in-page tabs.
- Can remember the Management Key for 3, 7, 30, or 90 days, or indefinitely, and sign in automatically on the next visit.
- Persists settings, encrypted credentials, batches, complete probe responses, and history in SQLite.
- Stores data beside the plugin by default and supports a custom location through
data-dir. - Matches the CPA Management Center light and dark themes.
- Follows the CPA Manager Plus language setting and supports Simplified Chinese, Traditional Chinese, English, and Russian.
CPA cannot place plugin-owned cards on its existing home dashboard. Balances are shown on this plugin's own Management Center page.
Download the archive for the CPA host platform and place the dynamic library in CPA's plugin discovery directory. Keep the library name unchanged because CPA derives the plugin ID from it:
plugins/windows/amd64/sub2api-balance.dll
plugins/linux/amd64/sub2api-balance.so
plugins/darwin/arm64/sub2api-balance.dylib
Enable the plugin in CPA:
plugins:
enabled: true
dir: "plugins"
configs:
sub2api-balance:
enabled: true
priority: 1
data-dir: ""Open Sub2API Balance from the CPA Management Center plugin menu. Use the CPA Management Key in CPA's built-in Manager, or the Manager Plus Admin Key when the page is opened through CPA Manager Plus. When “Remember Management Key” is selected, the key can be retained for 3, 7, 30, or 90 days, or indefinitely; 7 days is the default. After successful validation, the key and expiration time are stored as plaintext JSON in LocalStorage for the current site origin. Expiration, authentication failure, or “Sign out and forget key” removes the record. Ports 8317 and 8337 have different origins and therefore remember keys independently. This expiration only controls browser storage and does not change the underlying CPA or Manager Plus key lifetime.
The plugin exposes a string data-dir setting. An empty value preserves the original behavior: it resolves its loaded dynamic-library path with the operating-system module API and uses the adjacent cpa-plugin-sub2api-balance-data directory. It never uses the CPA working directory or os.Executable().
For this library:
plugins/windows/amd64/sub2api-balance.dll
the default data directory is beside it:
plugins/windows/amd64/cpa-plugin-sub2api-balance-data/
├── sub2api-balance.db
├── sub2api-balance.db-wal
├── sub2api-balance.db-shm
└── master.key
An absolute data-dir is used directly. A relative value is resolved from the plugin library directory. In Docker, specify a container-visible path and mount the corresponding volume; an unmounted Windows host path is not valid inside the container. Changing the setting switches to the independent dataset at the target path. The plugin does not move or delete the old directory. To retain existing data, stop CPA first and copy the database, WAL/SHM files, and master.key together.
The default or custom directory must be writable. In Docker, persist the plugin directory or mount the selected data directory as a writable volume. Back up the database and master.key together; encrypted credentials cannot be recovered without that key.
API Keys and authenticated proxy URLs are encrypted with AES-256-GCM. The random 32-byte master.key is created on first startup. API responses expose only masked key and proxy hints.
The effective proxy is selected in this order:
provider proxy > plugin global proxy > direct connection
Supported URL schemes are http, https, socks5, and socks5h. The plugin does not inherit environment or CPA global proxy variables.
CPA protects these exact routes with its native Management Key middleware:
The browser sends the key as Authorization: Bearer <management-key>. These plugin-owned routes work both directly through CPA's built-in Manager and through the CPA Manager Plus proxy.
GET /v0/management/sub2api-balance/state
PUT /v0/management/sub2api-balance/settings
PUT /v0/management/sub2api-balance/providers
POST /v0/management/sub2api-balance/refresh
GET /v0/management/sub2api-balance/history
The unauthenticated browser resource only serves the login shell:
GET /v0/resource/plugins/sub2api-balance/open
Go 1.26+, CGO, and a C compiler for the target platform are required.
make test
make vet
make build
make package VERSION=0.3.0Release archives contain one dynamic library at the zip root and a matching SHA-256 file. Tags matching v* trigger GitHub Actions builds for Linux, macOS, Windows, and FreeBSD, followed by a GitHub Release.