Invisible Wallet API

Make Web3 unseen

Shinami’s invisible wallets abstract away web3-specific elements like seed phrases, third-party wallet connections, gas fees, and signing popups. They are backend wallets under the shared custody of your app and Shinami. Shinami has built a proprietary compute-only service with no state persistence and strict input/output policies to allow both parties to transact together securely.

The Invisible Wallet API integrates with Shinami's Gas Station and Node Service for gasless transaction execution. This sections details the JSON-RPC methods for managing invisible wallets. Check out our TypeScript tutorial for more details on the end-to-end flow.

shinami_key_createSession

Description
For security purposes, you must generate a session token before you create a wallet, sign transactions, or execute transactions. Session tokens expire after 10 minutes.

Params

  • secret: <string> - Used to encrypt a user's wallet private key. Typically, this would tie to your app's registration and authentication
curl https://api.shinami.com/key/v1 \
-X POST \
-H 'X-API-Key: <<walletAccessKey>>' \
-H 'Content-Type: application/json' \
-d '{ "jsonrpc":"2.0", "method":"shinami_key_createSession", "params":["{{secret}}"], "id":1}'

Result
sessionToken: <string> - Used to create a wallet, sign transactions or execute transactions

shinami_wal_createWallet

Description
Programmatically generates a unique wallet for a user that is Sui network agnostic.

📘

The walletId passed in here will be paired up with the secret used to create your sessionToken, similar to a username/password pairing.

Params

  • walletId: <string> - An arbitrary and unique ID for the wallet. Can be based on your internal user IDs
  • sessionToken: <string>
curl https://api.shinami.com/wallet/v1 \
-X POST \
-H 'X-API-Key: <<walletAccessKey>>' \
-H 'Content-Type: application/json' \
-d '{
      "jsonrpc": "2.0",
      "method": "shinami_wal_createWallet",
      "params": [
        "{{walletId}}",
        "{{sessionToken}}"
      ],
      "id": 1
    }'

Result
WalletAddress: <SuiAddress> - Sui wallet address created for the user.

shinami_wal_getWallet

Description
Retrieve a user's wallet address based on their ID.

Params

  • walletId: <string> - An arbitrary and unique ID for the wallet. Can be based on your internal user IDs.
curl https://api.shinami.com/wallet/v1 \
-X POST \
-H 'X-API-Key: <<walletAccessKey>>' \
-H 'Content-Type: application/json' \
-d '{ "jsonrpc":"2.0", "method":"shinami_wal_getWallet", "params":["{{walletId}}"], "id":1}'

Result
WalletAddress: <SuiAddress> - Sui wallet address created for the user.

shinami_wal_signTransactionBlock

Description
Signs a fully constructed transaction block. This is a low level API - it requires integration with Gas Station API and Sui API for transaction sponsorship (if needed) and execution. This method gives you more control over how you submit transactions to Sui.

Params

  • walletId: <string> - An arbitrary and unique ID for the wallet. Can be based on your internal user IDs
  • sessionToken: <string>
  • txBytes : <Base64> - Transaction data bytes, as Base64 encoded string
curl https://api.shinami.com/wallet/v1 \
-X POST \
-H 'X-API-Key: <<walletAccessKey>>' \
-H 'Content-Type: application/json' \
-d '{
      "jsonrpc": "2.0",
      "method": "shinami_wal_signTransactionBlock",
      "params": [
        "{{walletId}}",
        "{{sessionToken}}",
        "{{txBytes}}"
      ],
      "id": 1
    }'

Result

  • signature : <Base64> - Base64 encoded transaction signature, signed by the wallet key
  • txDigest: <TransactionDigest>

shinami_wal_signPersonalMessage

Description
Signs a personal message using an invisible wallet. The signature can be verified with the PersonalMessage intent scope.

Params

  • walletId: <string> - An arbitrary and unique ID for the wallet. Can be based on your internal user IDs
  • sessionToken: <string>
  • message : <Base64> - Arbitrary message bytes, as Base64 encoded string
curl https://api.shinami.com/wallet/v1 \
-X POST \
-H 'X-API-Key: <<walletAccessKey>>' \
-H 'Content-Type: application/json' \
-d '{
      "jsonrpc": "2.0",
      "method": "shinami_wal_signPersonalMessage",
      "params": [
        "{{walletId}}",
        "{{sessionToken}}",
        "{{message}}"
      ],
      "id": 1
    }'

Result

signature : <Base64> - Base64 encoded signature, signed by the wallet key

shinami_wal_executeGaslessTransactionBlock

Description
Sponsors / signs / executes a gasless transaction from a wallet. This is a convenient end-to-end method for submitting sponsored transactions to the chain.

📘

To call this method, you need an access key that is authorized for all of these Shinami products:

  • Invisible Wallet
  • Gas Station
  • Node Service

Params

  • walletId: <string> - An arbitrary and unique ID for the wallet. Can be based on your internal user IDs
  • sessionToken: <string>
  • txBytes : <Base64> - Base64 encoded TransactionKind (as opposed to TransactionData) bytes
  • gasBudget : <CoinAmount> - The gas budget; the transaction will fail if the gas cost exceeds the budget
  • options : <TransactionBlockResponseOptions> - Optional. Sui options for specifying the transaction content to be returned
  • requestType : <ExecuteTransactionRequestType> - Optional. The execution request type (WaitForEffectsCert or WaitForLocalExecution)
curl https://api.shinami.com/wallet/v1 \
-X POST \
-H 'X-API-Key: <<allAccessKey>>' \
-H 'Content-Type: application/json' \
-d '{
      "jsonrpc": "2.0",
      "method": "shinami_wal_executeGaslessTransactionBlock",
      "params": [
        "{{walletId}}",
        "{{sessionToken}}",
        "{{txBytes}}",
        "{{gasBudget}}",
        {
          "showRawInput": true,
          "showEffects": true,
          "showEvents": false,
          "showObjectChanges": true,
          "showBalanceChanges": false
        },
        "{{requestType}}"
      ],
      "id": 1
    }'

Result
SuiTransactionBlockResponse : <SuiTransactionBlockResponse>

shinami_walx_setBeneficiary

📘

Beneficiary Graph API

This API interacts with the Account Graph Move package.

Description
Designates a beneficiary account for this wallet in the specified beneficiary graph instance. Calling this method multiple times will override the previous designations.

Apps participating in Bullshark Quests can use this method to link up Shinami invisible wallets with their users' self-custody wallets.

📘

To call this method, you need an access key that is authorized for all of these Shinami products:

  • Invisible Wallet
  • Gas Station
  • Node Service

Params

  • walletId: <string> - An arbitrary and unique ID for the wallet. Can be based on your internal user IDs
  • sessionToken: <string>
  • beneficiaryGraphId : <ObjectID> - Id of the beneficiary graph instance
  • beneficiaryAddress : <SuiAddress> - Address of the beneficiary account
curl https://api.shinami.com/wallet/v1 \
-X POST \
-H 'X-API-Key: <<allAccessKey>>' \
-H 'Content-Type: application/json' \
-d '{
      "jsonrpc": "2.0",
      "method": "shinami_walx_setBeneficiary",
      "params": [
        "{{walletId}}",
        "{{sessionToken}}",
        "{{beneficiaryGraphId}}",
        "{{beneficiaryAddress}}"
      ],
      "id": 1
    }'

Result
TransactionDigest : <TransactionDigest> - Transaction digest for this operation

shinami_walx_unsetBeneficiary

📘

Beneficiary Graph API

This API interacts with the Account Graph Move package.

Description
Clears any beneficiary designation for this wallet in the specified beneficiary graph instance.

📘

To call this method, you need an access key that is authorized for all of these Shinami products:

  • Invisible Wallet
  • Gas Station
  • Node Service

Params

  • walletId: <string> - An arbitrary and unique ID for the wallet. Can be based on your internal user IDs
  • sessionToken: <string>
  • beneficiaryGraphId : <ObjectID> - Id of the beneficiary graph instance
curl https://api.shinami.com/wallet/v1 \
-X POST \
-H 'X-API-Key: <<allAccessKey>>' \
-H 'Content-Type: application/json' \
-d '{
      "jsonrpc": "2.0",
      "method": "shinami_walx_unsetBeneficiary",
      "params": [
        "{{walletId}}",
        "{{sessionToken}}",
        "{{beneficiaryGraphId}}"
      ],
      "id": 1
    }'

Result
TransactionDigest : <TransactionDigest> - Transaction digest for this operation

shinami_walx_getBeneficiary

📘

Beneficiary Graph API

This API interacts with the Account Graph Move package.

Description
Gets the beneficiary designation for this wallet in the specified beneficiary graph instance.

This is a convenience method on top of suix_getDynamicFieldObject.

📘

To call this method, you need an access key that is authorized for all of these Shinami products:

  • Invisible Wallet
  • Node Service

Params

  • walletId: <string> - An arbitrary and unique ID for the wallet. Can be based on your internal user IDs
  • beneficiaryGraphId : <ObjectID> - Id of the beneficiary graph instance
curl https://api.shinami.com/wallet/v1 \
-X POST \
-H 'X-API-Key: <<allAccessKey>>' \
-H 'Content-Type: application/json' \
-d '{
      "jsonrpc": "2.0",
      "method": "shinami_walx_getBeneficiary",
      "params": [
        "{{walletId}}",
        "{{beneficiaryGraphId}}"
      ],
      "id": 1
    }'

Result
SuiAddress : <SuiAddress> - Beneficiary address, or null if no beneficiary is designated