Overview

Note: we made a starter-template and tutorial to quickly create your first zkLogin app!

zkLogin is a Sui primitive that allows users to transact on Sui using the OAuth login flows they're familiar with, eliminating the friction of handling cryptographic keys or remembering mnemonics. zkLogin can be thought of as a two-factor authentication scheme, since sending a transaction requires both a credential from a recent OAuth login and a salt managed by someone other than the OAuth provider (in this case, Shinami). To learn more, see the Sui Foundation's zkLogin doc..

You'll find API endpoints and key usage notes below. If you ever need help you can reach out to us.

Use Cases

When you want to offer your users a non-custodial wallet that doesn't require them to remember mnemonics and pass-phrases - only their OAuth provider password.

Authentication, Rate Limits, and Error Handling

Authentication

You authenticate via an access key passed in a header ('X-Api-Key: ACCESS_KEY') or in the request url, e.g. https://api.shinami.com/sui/zkprover/v1/ACCESS_KEY. We recommend using a request header and not putting access keys in your request URLs for reduced visibility (in logs, etc). These steps are done automatically by our TypeScript SDK.

For more information, including how to set up an access key with Wallet Services rights, see our Authentication and API Keys guide.

🚧

Call this API from your backend

Shinami Wallet Services do not support CORS requests, so if you call these APIs from your frontend you'll get a CORS error. This is for security reasons: exposed wallet information could lead to malicious actors signing transactions on behalf of your users.

Error Handling

See our Error Reference for guidance on the errors you may receive from our services, including a section on errors specific to the zkLogin wallet API.

Rate Limits

When you surpass the QPS limit for a key, we return a JSON-RPC error code -32010. We recommend implementing retries with a backoff to handle any rate limits errors that arise. You can also adjust the rate limits of your keys to better balance your QPS allotment across your keys.

We also have a limit of two zk proofs per address per minute. When you hit this limit, we return a JSON-RPC code -32012.

zkLogin Addresses

A zkLogin wallet address is derived from iss, aud, sub, salt in the OpenID connect response, where:

• iss: The OpenID provider.
• aud : The unique identifier assigned to your application by the OpenID provider.
• sub: The OpenID provider's locally unique and never reassigned identifier for the user.
• salt: A consistent, ideally unique, value used to unlink the OpenID identifier with the on-chain address.

As a result, a user will have a new zkLogin wallet address if any of the above values change. For example, if one of your users logs in via Google and then Twitch - or with one Google email and then another - and you use both credentials with zkLogin, each credential will be linked to a different address. To learn more, see the Sui Foundation's zkLogin doc.

Tutorial with E2E sample code

Check out our Next.js tutorial for guidance on running our zkLogin app starter template.

zkLogin wallet service methods

shinami_zkw_getOrCreateZkLoginWallet

Description
Retrieves a zkLogin wallet along with its associated salt, creating a new wallet if necessary. This method provides the option to create and use multiple zkLogin wallets per (user, OAuth provider) pair by using the optional subWallet parameter. Note that your users will already have a different zkLogin wallet for each OAuth provider they use, whose jwt you pass to this method (see zkLogin Addresses for more details).

On the free tier you have a limit of wallet creations per month as shown on the "Sui Wallet Services" tab of the billing page in your dashboard (where you can also see how to upgrade if needed). If you hit this limit, you will get a JSON-RPC code -32012 and should not retry. All other wallet operations will still work for the month, like signing with wallets you've already created.

Request Parameters

Example Request Template

The example below uses the Shinami Clients SDK.

Replace all instances of {{name}} with the actual value for that name

 curl https://api.shinami.com/zkwallet/v1 \
 -X POST \
 -H 'X-API-Key: {{walletAccessKey}}' \
 -H 'Content-Type: application/json' \
 -d '{
         "jsonrpc":"2.0", 
         "method":"shinami_zkw_getOrCreateZkLoginWallet", 
         "params":[
             "{{signedJWTToken}}"
         ], 
         "id":1
      }'

import { ZkWalletClient } from "@shinami/clients/sui";

// Obtain wallet access key from your Shinami web portal.
const zkw = new ZkWalletClient({{walletAccessKey}});

// Prepare a nonce according to the zkLogin requirements.
// Obtain a valid jwt with that nonce from a supported OpenID provider.

// Get zkLogin wallet salt.
await zkw.getOrCreateZkLoginWallet({{jwt}});

Example Response

{
    "jsonrpc": "2.0",
    "result": {
        "userId": {
            "iss": "https://id.twitch.tv/oauth2",
            "aud": "2bc0920c90ufn0adomxlca3pldbdpo",
            "keyClaimName": "sub",
            "keyClaimValue": "984333370"
        },
        "subWallet": 0,
        "salt": "kL+fRWN8888cKl5D72qzCQ==",
        "address": "0x6a7b07da9d2c210bbbe044dbe29f0c5ae20444584a4d8ee9a804839f8256ea3c"
    },
    "id": 1
}

{
    userId: {
        iss: 'https://id.twitch.tv/oauth2',
        aud: '2bc0920c90ufn0adomxlca3pldbdpo',
        keyClaimName: 'sub',
        keyClaimValue: '984333370'
    },
    subWallet: 0,
    salt: 192403790493605555550623021243959522057n,
    address: '0x6a7b07da9d2c210bbbe044dbe29f0c5ae20444584a4d8ee9a804839f8256ea3c'
}

Response Data

zkProver service methods

shinami_zkp_createZkLoginProof

Description
Generate a zkLogin proof prior to signing and executing a transaction. The example below uses the Shinami Clients SDK.

Notes:

• Devnet has a different zkey than Testnet and Mainnet. Shinami's zk prover currently only works with Testnet and Mainnet.
• We have a limit of two zk proofs per address per minute. When you hit this limit, we return a JSON-RPC code -32012.

Request Parameters

Example Request Template

Replace all instances of {{name}} with the actual value for that name

curl https://api.shinami.com/zkprover/v1 \
-X POST \
-H 'X-API-Key: {{walletAccessKey}}' \
-H 'Content-Type: application/json' \
-d '{
        "jsonrpc":"2.0", 
        "method":"shinami_zkp_createZkLoginProof", 
        "params":[
            "{{jwt}}",
            "{{maxEpoch}}",
            "{{extendedEphemeralPublicKey}}",
            "{{jwtRandomness}}",
            "{{salt}}"
        ], 
        "id":1
    }'

import { ZkProverClient } from "@shinami/clients/sui";

// Obtain wallet access key from your Shinami web portal.
const zkp = new ZkProverClient({{walletAccessKey}});

// Create a zkProof.
await zkp.createZkLoginProof(
    {{jwt}},
    {{maxEpoch}},
    {{ephemeralPublicKey}},
    {{jwtRandomness}},
    {{salt}}
);

// Now you can sign transaction blocks with ephemeralPrivateKey, and assemble the zkLogin signature
// using zkProof.

Example Response

{
    "jsonrpc": "2.0",
    "result": {
        "zkProof": {
            "proofPoints": {
                "a": ["15523188928150068463877187176143113666714843703470604151076285692983325640642", "5937622317780822197753258881898720685630444182643789312895382585679701582730", "1"],
                "b": [
                    ["16826302723856343423452057269835204629749355045593813315170205467027472681113", "13797818130832460450334887874511731864855590610477696974834238052347712422314"],
                    ["13373917712679082794928414217966585760669198351828608413595476883128268622714", "5700527829855762859349841977943997112007134227264278415875624634861579977183"],
                    ["1", "0"]
                ],
                "c": ["7520248514700601656024563691610669758825183429353083260336955084416144661718", "20552359067831153630006195193902483617859079319246848227965146473634030062290", "1"]
            },
            "issBase64Details": {
                "value": "wiaXNzIjoiaHR0cHM6Ly9pZC50d2l0Y2gudHYvb2F1dGgyIiw",
                "indexMod4": 2
            },
            "headerBase64": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEifQ"
        }
    },
    "id": 1
}

{
    proofPoints: {
        a: [
            '10210145730043037811940974600447596138332245137712632111543948579663620583434',
            '7161160787659733995589070724990899004457677439433421417304252171408748983773',
            '1'
        ],
        b: [ [Array], [Array], [Array] ],
        c: [
            '14336916288409630215040261300089886420211729238372809076105326107110995622366',
            '16791539167604801843541798961147781044566621780138018818605704529730677460898',
            '1'
        ]
    },
    issBase64Details: {
        value: 'wiaXNzIjoiaHR0cHM6Ly9pZC50d2l0Y2gudHYvb2F1dGgyIiw',
        indexMod4: 2
    },
    headerBase64: 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEifQ'
}

Response Data