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