REST vs gRPC

REST

All Mnemonic APIs by default are implemented as REST API supporting JSON standard.

Endpoints

The REST API endpoints are provided below:

Chain	Endpoint
Ethereum	ethereum-rest.api.mnemonichq.com
Polygon	polygon-rest.api.mnemonichq.com
Optimism	optimism-rest.api.mnemonichq.com

Authentication

Authenticated requests must include a valid API key.

REST HTTP clients need to pass a header key X-API-Key with the corresponding API key value with each request.

curl https://ethereum-rest.api.mnemonichq.com/<endpoint> \
    -H "X-API-Key: YOUR_API_KEY_HERE" \'

import requests # requires `pip install requests`

result = requests.get(
    'https://ethereum-rest.api.mnemonichq.com/<endpoint>',
    headers={'x-api-key': 'YOUR_API_KEY_HERE'}
).json()

const axios = require('axios');

const reqUrl = 'https://ethereum-rest.api.mnemonichq.com';
const headers = { 'X-API-Key': 'YOUR_API_KEY_HERE' };

axios.get(reqUrl, { headers: headers })
  .then(response => {
    console.log(response.status);
    console.log(response.headers);
    console.log(response.data);
  })
  .catch(error => {
    console.error(error);
  });

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {
  reqUrl := "https://ethereum-rest.api.mnemonichq.com"

  req, _ := http.NewRequest("GET", reqUrl, nil)
  req.Header.Add("X-API-Key", "YOUR_API_KEY_HERE")
}

gRPC / Protobuf

Mnemonic API also provide a gRPC interface.

A language-agnostic specification for this API is defined using Protocol Buffers (v3), which can be used to generate client libraries in a variety of programming languages.

The Protobuf source files can be found in Mnemonic public Buf repository.

Assets and Libraries

Mnemonic uses buf to generate and manage client libraries and documentation based on the Protobuf specification. Explore Buf documentation to learn more about how to generate clients in various languages.

Documentation

Explore our buf-generated docs.

Endpoints

The gRPC API endpoints are provided below:

Chain	Endpoint
Ethereum	ethereum-grpc.api.mnemonichq.com
Polygon	polygon-grpc.api.mnemonichq.com
Optimism	optimism-grpc.api.mnemonichq.com

Authentication

Authenticated requests must include a valid API key.

Note: In beta only one API key is issued per user. The key can be rotated if necessary upon request.

gRPC clients need to pass the key value as x-api-key in the metadata section of the RPC.

package main

import (
    "context"

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

func main() {
    // ... your grpc client configuration
    c := pb.NewGreeterClient(conn)

    ctx := context.Background()
    ctx = metadata.AppendToOutgoingContext(ctx, "x-api-key", "YOUR_API_KEY_HERE")

    r, err := c.SayHello(ctx, &pb.HelloRequest{Name: name})
}

import grpc
import your_pb2
import your_pb2_grpc

def main():
    # ... your grpc client configuration
    channel = grpc.insecure_channel('your_grpc_server_address:port')
    stub = your_pb2_grpc.GreeterStub(channel)

    metadata = [('x-api-key', 'YOUR_API_KEY_HERE')]
    ctx = grpc.metadata_call_credentials(metadata)
    call_credentials = grpc.composite_call_credentials(grpc.ssl_channel_credentials(), ctx)
    secure_channel = grpc.secure_channel('your_grpc_server_address:port', call_credentials)
    secure_stub = your_pb2_grpc.GreeterStub(secure_channel)

    request = your_pb2.HelloRequest(name='your_name')
    response = secure_stub.SayHello(request)

if __name__ == '__main__':
    main()

const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const path = require('path');

const PROTO_PATH = path.join(__dirname, 'path/to/your/protofile.proto');
const packageDefinition = protoLoader.loadSync(PROTO_PATH, {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true,
});

const yourProto = grpc.loadPackageDefinition(packageDefinition);
const GreeterService = yourProto.yourProtoPackageName.Greeter;

function main() {
  const client = new GreeterService(
    'your_grpc_server_address:port',
    grpc.credentials.createInsecure(),
  );

  const metadata = new grpc.Metadata();
  metadata.add('x-api-key', 'YOUR_API_KEY_HERE');

  const request = {
    name: 'your_name',
  };

  client.sayHello(request, metadata, (error, response) => {
    if (error) {
      console.error(error);
    } else {
      console.log(response);
    }
  });
}

main();

You must provide a TLS configuration for the gRPC client connection.

creds := credentials.NewTLS(&tls.Config{})
conn, err = grpc.Dial(target, grpc.WithTransportCredentials(creds))

import grpc
import ssl

# ... your existing Python gRPC client code

# Create a secure channel using TLS
creds = grpc.ssl_channel_credentials()
secure_channel = grpc.secure_channel('your_grpc_server_address:port', creds)
stub = your_pb2_grpc.GreeterStub(secure_channel)

# ... the rest of your Python gRPC client code

const grpc = require('@grpc/grpc-js');
const fs = require('fs');

// ... your existing Node.js gRPC client code

// Create a secure channel using TLS
const creds = grpc.credentials.createSsl();
const secureClient = new GreeterService(
  'your_grpc_server_address:port',
  creds,
);

// ... the rest of your Node.js gRPC client code