Skip to main content

Getting Started

We support both gRPC and REST​

The MPCVault Platform API is built primarily on gRPC, a high-performance, open-source RPC framework developed by Google. It offers several advantages over traditional JSON-based APIs:

  • Client libraries can be generated directly from Protobuf definitions, reducing boilerplate and integration errors.
  • Applications interact with MPCVault methods as if calling local objects—no need to manage HTTP requests manually.
  • Protobuf is more efficient than JSON in both size and serialization speed.
  • gRPC uses a single multiplexed TCP connection, reducing latency and improving responsiveness.

For those who prefer conventional integration, a REST API is also available and provides access to the same core functionality.

Full API definitions are available in our GitHub repo and in the API Reference section of this documentation.

gRPC methods are easy to work with. Refer to the Protobuf files in the repository for full details. Once compiled, the comments in the definitions will appear as inline documentation in your generated client.

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.