API Guide

Choosing An API Server

For HTTP requests:

Domain	Type
https://api.mixin.one	Global
https://mixin-api.zeromesh.net	China Or Global

For WebSocket requests:

Domain	Type
wss://blaze.mixin.one	Global
wss://mixin-blaze.zeromesh.net	China Or Global

Calling APIs

Most APIs need to signed with a JSON Web Tokens (JWT) to access. They utilizes secure data transmissions between clients and servers.

Signing

tip

Most Mixin SDK has already provide a JWT generator, and thet can handle the JWT generation and verification automatically. For more information, please refer to SDK section.

JWT Header

Parameter	Instruction
alg	Signature Algorithm, set to EdDSA
typ	Token type, set to JWT

JWT Payload

Parameter	Instruction
uid	User Id
sid	Session Id
iat	issued at
exp	Expiration Time
jti	JWT ID
sig	Signature
scp	FULL or special scope

Sign JWT in Go language

/*
* uid: User Id
* sid: Session Id
* secret: PrivateKey
* method: HTTP Request method, e.g.: GET, POST
* url: URL path without hostname, e.g.: /transfers
* body: HTTP Request body, e.g.: {"pin": "encrypted pin token"}
*/
func SignAuthenticationToken(uid, sid, secret, method, uri, body string) (string, error) {
  expire := time.Now().UTC().Add(time.Hour * 24 * 30 * 3)
  sum := sha256.Sum256([]byte(method + uri + body))
  token := jwt.NewWithClaims(jwt.EdDSA, jwt.MapClaims{
      "uid": uid,
      "sid": sid,
      "iat": time.Now().UTC().Unix(),
      "exp": expire.Unix(),
      "jti": uuid.NewV4().String(),
      "sig": hex.EncodeToString(sum[:]),
      "scp": "FULL", // or "PROFILE:READ MESSAGES:REPRESENT"
  })

 priv, err := base64.RawURLEncoding.DecodeString(privateKey)
  if err != nil {
    return "", err
  }
 token, err := jwt.Sign(jwt.EdDSA, ed25519.PrivateKey(priv), claims)
  return string(token), err
}

A example of signed token

eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1MzMwOTY0ODUsImlhdCI6MTUyNTMyMDQ4NSwianRpIjoiMjU5NGFkNTctOWRhZC00MjRmLTg1OTUtYjE0NzI3ZTI0ZTYxIiwic2lkIjoiYzA5Y2YzMTMtN2RlZC00MjVkLWFkM2YtYTFjZTRjZmQ1ZTVlIiwic2lnIjoiODVkZDIzOGE5ODM0NzE3ZGMxM2QzODQ0ZjYzYTFmZWUxM2Q4MmQyZTZjMmVlNDRlYWM3Yzc5MGY1ZGIyNWY4OCIsInVpZCI6Ijg5ZTBiZGVlLWMzNTUtNDdmMi05NDVhLWJlNDhiZTg3NTYwNiJ9.PYg6Cx5grs0flJe862R3VLEWKyTZPcXOGYF9RouztgR_mi3kleIzJt4vCwUZI9F7QrHBFMtTc3_wG_ymnnjsmnm0pBdoON4I-RxeaztIlyc1Ey9lLFe6_ARRUBXo_15ZORilS1hRdMREd84eQOLlO0ChieBPY0tSSiVqTaFZt3Q

You can decode it at jwt.io.

Send Requests with Token

Add signed authentication token to the headers of API requests to get current dApp's profile:

curl -i -H "Content-Type: application/json" \
        -H "Authorization: Bearer YOUR_TOKEN_HERE" \
        "https://api.mixin.one/me"

API Responses

The HTTP status codes returned by the Mixin APIs meet the RFC specifications.

On success:

{
  "data": {...}
}

or

{
  "data": [...]
}

On error:

{
  "error": {
    "status": 500,
    "code": 500,
    "description": "Internal Server Error"
  }
}

For more, please refer to error code Document。