Skip to main content

​
Overview

The WalletService provides a comprehensive gRPC API for interacting with the Muun Wallet libwallet. It includes operations for NFC security cards, diagnostic mode, recovery code setup, and key-value storage.

​
Service Definition

service WalletService {
  // Security Card Operations
  rpc SetupSecurityCard(google.protobuf.Empty) returns (XpubResponse);
  rpc ResetSecurityCard(google.protobuf.Empty) returns (google.protobuf.Empty);
  rpc SignMessageSecurityCard(SignMessageSecurityCardRequest) returns (SignMessageSecurityCardResponse);
  rpc SetupSecurityCardV2(google.protobuf.Empty) returns (SetupSecurityCardResponse);
  rpc SignMessageSecurityCardV2(google.protobuf.Empty) returns (google.protobuf.Empty);

  // Diagnostic Mode Operations
  rpc StartDiagnosticSession(google.protobuf.Empty) returns (DiagnosticSessionDescriptor);
  rpc PerformDiagnosticScanForUtxos(DiagnosticSessionDescriptor) returns (stream ScanProgressUpdate);
  rpc SubmitDiagnosticLog(DiagnosticSessionDescriptor) returns (DiagnosticSubmitStatus);
  rpc PrepareSweepTx(PrepareSweepTxRequest) returns (PrepareSweepTxResponse);
  rpc SignAndBroadcastSweepTx(SignAndBroadcastSweepTxRequest) returns (SignAndBroadcastSweepTxResponse);

  // Recovery Code Setup
  rpc StartChallengeSetup(ChallengeSetupRequest) returns (SetupChallengeResponse);
  rpc FinishRecoveryCodeSetup(FinishRecoveryCodeSetupRequest) returns (google.protobuf.Empty);
  rpc PopulateEncryptedMuunKey(PopulateEncryptedMuunKeyRequest) returns (google.protobuf.Empty);

  // Key-Value Storage
  rpc Save(SaveRequest) returns (google.protobuf.Empty);
  rpc Get(GetRequest) returns (GetResponse);
  rpc Delete(DeleteRequest) returns (google.protobuf.Empty);
  rpc SaveBatch(SaveBatchRequest) returns (google.protobuf.Empty);
  rpc GetBatch(GetBatchRequest) returns (GetBatchResponse);
  rpc GetByPrefix(GetByPrefixRequest) returns (GetBatchResponse);
}

​
Security Card Operations

​
SetupSecurityCard

Initialize a new NFC security card and retrieve its extended public key. Request: google.protobuf.Empty Response: XpubResponse
​
base58_xpub
string
The base58-encoded extended public key of the security card

​
SetupSecurityCardV2

Initialize a new NFC security card (V2 protocol) with enhanced validation. Request: google.protobuf.Empty Response: SetupSecurityCardResponse
​
is_known_provider
bool
Indicates whether the card provider is recognized
​
is_card_already_used
bool
Indicates whether the card has been previously used

​
SignMessageSecurityCard

Sign a message using the NFC security card. Request: SignMessageSecurityCardRequest
​
message_hex
string
required
The message to sign, encoded in hexadecimal format
Response: SignMessageSecurityCardResponse
​
signed_message_hex
string
The signed message in hexadecimal format
​
is_validated
bool
Indicates whether the signature was successfully validated

​
ResetSecurityCard

Reset the NFC security card to its factory state. Request: google.protobuf.Empty Response: google.protobuf.Empty

​
SignMessageSecurityCardV2

Sign a message using the NFC security card (V2 protocol). Request: google.protobuf.Empty Response: google.protobuf.Empty

​
Diagnostic Mode Operations

See Diagnostic Mode APIs for detailed documentation.

​
Recovery Code Setup

​
StartChallengeSetup

Initiate the recovery code challenge setup process. Request: ChallengeSetupRequest
​
type
string
required
The type of challenge being set up
​
public_key
string
required
The public key for the recovery code
​
salt
string
required
Salt value for key derivation
​
encrypted_private_key
string
required
The encrypted private key
​
version
int32
required
Version number of the challenge setup protocol
Response: SetupChallengeResponse
​
muun_key
string
The Muun server key (optional)
​
muun_key_fingerprint
string
Fingerprint of the Muun key for verification (optional)

​
FinishRecoveryCodeSetup

Complete the recovery code setup process. Request: FinishRecoveryCodeSetupRequest
​
recovery_code_public_key_hex
string
required
The recovery code public key in hexadecimal format
Response: google.protobuf.Empty

​
PopulateEncryptedMuunKey

Populate the encrypted Muun key during recovery setup. Request: PopulateEncryptedMuunKeyRequest
​
recovery_code_public_key_hex
string
required
The recovery code public key in hexadecimal format
Response: google.protobuf.Empty

​
Key-Value Storage Operations

See Key-Value Storage APIs for detailed documentation.

​
Error Handling

All RPC methods may return errors with the following structure: 
enum ErrorType {
  CLIENT = 0;      // Client-side error
  LIBWALLET = 1;   // Libwallet error
  HOUSTON = 2;     // Server-side error
}

message ErrorDetail {
  ErrorType type = 1;
  int64 code = 2;
  string message = 3;
  string developer_message = 4;
}
​
type
ErrorType
The category of error (CLIENT, LIBWALLET, or HOUSTON)
​
code
int64
Numeric error code for programmatic handling
​
message
string
Human-readable error message
​
developer_message
string
Detailed error message for debugging

​
Source Reference

Protobuf definition: libwallet/presentation/api/wallet_service.proto

Build docs developers (and LLMs) love

Get started for freeTalk to us