Getting Started

We use gRPC

The MPCVault Platform API is built upon gRPC, a powerful, open-source RPC framework developed by Google. It offers several advantages compared to a JSON API interface:

• Client libraries can be compiled from the interface definition files (proto files). Developers no longer have to write code that converts the JSON definition to local classes, saving development time and reducing room for error.
• A client application can interact with methods offered by the MPCVault as though it were calling a local object. There is no need to write and manage HTTP calls anymore, simplifying development.
• gRPC uses Protobuf for encoding, which is very space-efficient and CPU-efficient compared to JSON, saving network bandwidth and reducing CPU time spent on serialization and deserialization.
• gRPC handles RPC calls using a single TCP connection using multiplexing, decreasing request latency and increasing application responsiveness.

All of MPCVault's API definitions can be found in this GitHub repo. Link.

The methods within the gRPC API are 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.

Examples

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

Sanity Testing and handling public keys

When you generate a wallet on MPCVault, you are strongly encouraged to perform a sanity test by either completing an outgoing transaction or signing a message using that wallet.

While our system returns the public key associated with the wallet address created when you call our API, this is meant to help you construct certain transactions using the raw signing method directly with ECDSA and the EdDSA algorithms, such as with Apotos and Solana.

You should not attempt to generate the wallet address based on this public key yourself, as this is a very error-prone process. Instead, you should use our returned wallet address. You can, of course, generate the wallet address based on the returned public key and compare it against the returned address. However, this is not a replacement for the sanity testing that you are required to perform as aforementioned.

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 requests. API keys can be viewed and managed in the Dashboard. Unauthenticated API requests will fail.

{Your API Token} does not contain any information associated with your cryptographic keys used for asset custody. It solely serves as an authentication credential.

🚧 Caution! Nevertheless, 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.

Idempotent Requests

This feature is only available upon request.

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.