Skip to main content

API Guide

Choosing An API Server#

For HTTP requests:

DomainType
https://api.mixin.oneGlobal
https://mixin-api.zeromesh.netChina Or Global

For WebSocket requests:

DomainType
wss://blaze.mixin.oneGlobal
wss://mixin-blaze.zeromesh.netChina 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#

ParameterInstruction
algSignature Algorithm, set to EdDSA
typToken type, set to JWT

JWT Payload#

ParameterInstruction
uidUser Id
sidSession Id
iatissued at
expExpiration Time
jtiJWT ID
sigSignature
scpFULL 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