MPCVault API Documentation

The MPCVault API is built upon gRPC, a powerful, open-source RPC framework developed by Google that enables easier construction of distributed applications and services. With gRPC, a client application can interact with methods on server applications on a different machine as though it were a local object. This framework allows developers to bypass the need to manually build new classes and objects for encoding and decoding requests and their data fields, simplifying development.

Examples

You can find examples of API implementation in different languages here.

API Types

MPCVault provides two API services – the Platform API and the Wallet API.

• The Platform API's keys don't store any cryptographic materials. While they can be used to build custom transactions, these still need to be signed with your phone.

• The Wallet API, on the other hand, enables wallet provisioning and transaction signing without the need for a mobile device. This feature is currently in beta. If you're interested in joining, please contact us at info [at] mpcvault.com.

API Endpoint

The gRPC endpoint is api.mpcvault.com:443

Authentication

The MPCVault API uses gRPC Header authentication. Please attach x-mtoken: {Your API Token} header to all your gRPC request. API keys can be viewed and managed in the Dashboard. Unauthenticated API requests will fail.

🚧 Caution! API keys have extensive privileges, so keep them secure. Avoid sharing your keys in publicly accessible areas like GitHub, client-side code, etc.

TLS Enforcement

All API requests must be made with both gRPC transport credentials enabled and TLS >= 1.2.

🚧 Caution! Your request WILL FAIL if you don't use a secure connection.

For example, you should establish a secure connection like this in Python:

channel = grpc.secure_channel('api.mpcvault.com:443', grpc.ssl_channel_credentials())

Here's an example in GoLang:

package main

import (
	"log"

	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials"
)

func main() {
	creds, err := credentials.NewClientTLSFromCert(nil, "")
	if err != nil {
		log.Fatalf("Failed to create TLS credentials: %v", err)
	}

	conn, err := grpc.Dial("api.mpcvault.com:443", grpc.WithTransportCredentials(creds))
	if err != nil {
		log.Fatalf("Failed to connect to server: %v", err)
	}
	defer conn.Close()

	// Use the "conn" variable for further grpc calls
}

In this case, credentials.NewClientTLSFromCert(nil, "") will use the system's root certificate pool to create the TLS credentials.

IP Restrictions

To ensure all requests originate from your server, set up an allowed IP origins list. Any requests with valid credentials attempted from outside this list will trigger an alert.

Please use CIDR notation when specifying allowed ip blocks for both IPv4 and IPv6 when configuring your API user. You can find out more about it here.

API methods and documentation

The methods within the gRPC API are straightforward and easy to understand. For additional details, kindly refer to the interface definition files present in this repository. Upon compiling the Protobuf files into your respective language bindings, the comments found within the Protobuf will also be visible as comments for the gRPC functions.

Idempotent Requests

This feature is only available for Wallet APIs.

The API supports idempotency, permitting safe retrying of requests without causing duplicate operations. This is especially useful during network disruptions. For instance, if a network error occurs while creating a transfer, retrying the request with the same idempotency key ensures only one transfer is created.

Submit an additional idempotency-key in the request header for idempotent requests. MPCVault's idempotency records the resulting status code and body of the first request made with a given idempotency key, irrespective of its success. Subsequent requests with identical keys yield identical results, inclusive of the 500 errors.

An idempotency key is a client-generated unique value recognized by the server for identifying repeat requests. Clients decide on key creation, but we recommend V4 UUIDs or other random strings with substantial entropy to deter collisions. These keys may contain up to 255 characters.

Keys at least 24 hours old may be automatically removed from the system, and a new request is created for reused keys once the original is pruned.

The idempotency layer compares incoming parameters to that of the original request and denies them unless identical, preventing misuse.

Results are only stored if an API endpoint initiated execution. In cases where incoming parameters fail validation, or concurrent execution results in a conflict, no idempotency result is stored.

Methods featuring idempotent execution will be properly labeled. Not every method requires idempotent protection, as requests like key detail queries result in no state change.