API access requires authentication and network access. This was introduced in main release 2.0.0 (and dev/test 1.6.1) to:
  1. Prevent unauthorized access to the API and the wallet in case of network or firewall mis-configuration.
  2. Enable governed access for AI agents — agents should have scoped access to the API, not full admin.

​
Files involved

Override paths via env vars: When the cookie file does not exist, the proxy-router auto-generates one:
  • admin is the administrator username.
  • The trailing string is a randomly generated password.

​
Proxy configuration file

proxy.conf stores user credentials (rpcauth=) and permission whitelists (rpcwhitelist=):

​
Adding a scoped user

The agent user can only call get_balance. The admin user retains full access.

​
HTTP endpoints to manage users

Both endpoints require Basic Auth (administrator credentials).

​
Add or update a user

POST /auth/users — application/json

​
Remove a user

DELETE /auth/users — application/json

​
Authorization header

All endpoints require:
For example, YWRtaW46SkpMUk56ZTA4Wk4zdmxOZGd3Z2JyaDZjNGRSdzlnUVQ= decodes to admin:JJLRNze08ZN3vlNdgwgbrh6c4dRw9gQT.

​
Permission methods

These method names are recognized in rpcwhitelist= entries (e.g. rpcwhitelist=agent:get_balance,get_transactions). Set rpcwhitelistdefault=1 to allow them by default unless restricted.

​
Recommendations

  • For prosumer / agent setups, add per-agent users with restricted whitelists — never share the admin password with agents.
  • For TEE / SecretVM deployments, set COOKIE_CONTENT=admin:<strong-pw> in your encrypted env so the .cookie is seeded from secrets.
  • Rotate the admin password regularly. Keep proxy.conf out of version control.