Authentication Method
TLS Mutual Authentication (mTLS) + Token

Obtain the token by calling /system/login.
For authenticated requests, include the token in the header:
X-Molly-Wallet-Token: {user.X-Molly-Wallet-Token}
Validity Period: 5 minutes. A new login is required to obtain a fresh token after expiration.
There are three types of Tokens:

PasswordAuthToken

Obtained by logging in with name and password. This token has limited permissions—it can only access the ServiceAuthCert retrieval endpoint (/system/service/auth_cert) and has no access to other APIs.

SystemAuthToken

Obtained by authenticating with the system administrator's ServiceAuthCert. This token grants full access to all API endpoints.

NamespaceAuthToken

Obtained by authenticating with a Namespace's ServiceAuthCert. This token has scoped permissions—it can only access APIs under its own namespace (/namespaces/{uuid}).

For detailed instructions on login procedures and ServiceAuthCert retrieval, please refer to the respective API endpoint documentation.

Content-Type
application/json

Standard Successful Response Format

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

Certificate Note
The API uses self-signed TLS certificates. Clients must validate the server certificate using the provided root CA certificate.
⚠️ Please contact your system administrator to obtain the API key and the root certificate required for secure communication.

Error Response Format

For unsuccessful requests, the API returns a standardized error response in the following JSON format:

{
  "code": 400,
  "message": "Invalid parameter: token_address is required"
}

code: Numeric error code indicating the error type
message: Human-readable description of the specific error (may include contextual details)

Common Error Codes

Error Code	Error Message	Description
0	Success	Operation completed successfully
400	Bad Request	Client request error
500	Internal Error	Internal server error
501	Service Error	Service-level error
600	Risk Level Too High	Risk level exceeds threshold
601	Address Blacklisted	Address is on the blacklist
602	Insufficient Balance	Account balance is insufficient
603	Invalid Address	Provided address is invalid
604	KMS Error	Key Management System error
605	Chain Sync Error	Blockchain synchronization issue
606	Rate Limit Exceeded	Request frequency limit exceeded
607	Maintenance Mode	Service temporarily unavailable (maintenance)

Note:

code: 0 represents success (see Standard Successful Response Format in Overview).

Actual message content may vary per request to provide specific diagnostic information.