Overview

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

Note:

• code: 0 represents success (see Standard Successful Response Format in Overview).
• Actual message content may vary per request to provide specific diagnostic information.