​
Overview

Shinami’s Invisible Wallets abstract away Web3 elements like seed phrases, third-party wallet connections, gas fees, and signing popups. They are embedded, backend wallets under the shared custody of your app and Shinami. Both parties must cooperate in order to obtain a valid signature. You’ll find API endpoints and key usage notes below. If you ever need help you can reach out to us.

​
Use Cases

Core use cases include app-managed NFTs or closed-loop tokens. For a breakdown of the wallets we offer and wallet use-cases, see our high-level guide.

​
Shinami Gas Station Integration

All methods below that write to the Aptos blockchain have their gas fees sponsored by you via a Gas Station fund you create. This is because Invisible Wallets are designed to easily onboard Web2-native users (who may not want to download a wallet app, manage a seed phrase, and complete KYC checks to buy APT for gas). See the Aptos Gas Station FAQ page in our Help Center for how guidance on how to set up a fund.

​
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 (https://api.us1.shinami.com/aptos/wallet/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. Region URLs - us1 above - only work with API keys created in the same region. So, to use this API, you’ll make Wallet Services API keys in our US East - us1 region. See our Authentication and API Keys guide for how to set up a Wallet-Services-only access key and an access key with Wallet Services and Gas Station rights (needed to execute transactions and initialize Invisible Wallets on chain).
Call this API from your backendShinami Wallet Services do not support CORS requests, so if you make requests to these APIs from your frontend you’ll get a CORS error. This is for security reasons: exposed keys and wallet information could lead to malicious actors signing transactions on behalf of your users.
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. 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 Invisible Wallet API.

​
WalletId and Secret Pairing

When you create an Invisible Wallet, you must create, store, link, and never change the following two values:
  • walletId: Your internal id for a wallet. When you provide us a walletId in a method call, it tells us which Invisible Wallet to use. It could be your internal userId value, or a new arbitrary and unique value you link to the userId.
  • secret: Your internal secret for a wallet. The sessionToken you generate with it is combined with Shinami data to obtain a signature from the associated wallet. Ideally it would be different for each wallet so that if one secret is compromised the rest are not.
When you create an Invisible Wallet, you forever link its walletId it to the secret you used:
So, if you try to use the walletId with a different secret, you’ll get an error:

​
Tutorial with E2E sample code

Check out our TypeScript tutorial for more code samples and details on the end-to-end flow of creating and using Invisible Wallets to execute sponsored transactions.

​
Methods

​
key_createSession

For security purposes, you must generate a session token before you create a wallet, or sign/execute transactions. Session tokens are valid and can be reused for 10 minutes. You may also use an instance of ShinamiWalletSigner to manage session token generation and refreshes for a given wallet. This is shown in the methods below that have a sessionToken parameter in an additional sample code tab. Request Parameters
NameTypeDescription
secretstringUsed to encrypt and decrypt a wallet’s private key. Therefore, it must always be used with the same walletId and cannot be changed in the future (see walletId and secret pairing)
Example Request Template The TypeScript example uses the Shinami Clients SDK, which you can install with: 
npm install @shinami/clients
Replace all instances of {{name}} with the actual value for that name. 
curl https://api.us1.shinami.com/aptos/key/v1 \
-X POST \
-H 'X-API-Key: {{walletServicesAccessKey}}' \
-H 'Content-Type: application/json' \
-d '{
        "jsonrpc":"2.0",
        "method":"key_createSession",
        "params":[
            "{{secret}}"
        ],
        "id":1
    }'
Example Response 
{
     "jsonrpc":"2.0",
     "result":"eyJraWQiOiJrZXkyMDIzMDgxMSIsImVuYyI6IkEyNTZHQ00iLCJ0YWciOiI4SVpQWXlHeDlmOTd6U2NIdmN6N3lnIiwiYWxnIjoiQTI1NkdDTUtXIiwiaXYiOiJQWVJXZFJrbnNMMlNnVzhfIn0.ygDCI-NcvUcH7wYc0Bp0-59qeIfGOqLyXZGsLF4pW0M.aOAW0AwBvAWpaS-S.QmesdNIdNIYbT59RET-lNuzNMUvS-xb2exhXrAIlspnIkV3nuBx7PKC_GgJ7C1EqJx3tDtQaLLDGdrO8_s-75oK88ls5mzDRR-w2A0VdCcTH0_JwsQgijIbCKFWS0g.dULMzxZ4gGbm2unqOnzv8w",
     "id": 1
}
Response Data
TypeDescription
stringsessionToken corresponding to the provided secret. Valid and can be reused for 10 minutes.

​
wal_createWallet

Creates a new Shinami Invisible Wallet you control, but does not yet initialize the address on an Aptos network (e.g. Mainnet). Generally, you can wait to initialize a wallet if you wish (see more in the description of wal_initializeWalletOnChain). Wallet creation limit On the free tier you have a limit of wallet creations per month as shown on the “Aptos 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
NameTypeDescription
walletIdstringA unique ID you maintain for the wallet. Can be based on your internal user IDs. Note: you cannot change this value in the future, so do not use a value that you or your users might change, such as a editable username.
sessionTokenstringThe token generated by shinami_key_createSession with the unalterable secret you will permanently associate with this walletId (and, ideally, only this walletId).
Example Request Template The TypeScript example uses the Shinami Clients SDK, which you can install with: 
npm install @shinami/clients
Replace all instances of {{name}} with the actual value for that name. 
curl https://api.us1.shinami.com/aptos/wallet/v1 \
-X POST \
-H 'X-API-Key: {{walletServicesAccessKey}}' \
-H 'Content-Type: application/json' \
-d '{
        "jsonrpc": "2.0",
        "method": "wal_createWallet",
        "params": [
            "{{walletId}}",
            "{{sessionToken}}"
        ],
        "id": 1
    }'
Example Response 
{
   "id" : 1,
   "jsonrpc" : "2.0",
   "result" : {
      "accountAddress" : "0x45329e69bf823b556ab930a244ab33e0a71f4065d52b4a763e51af2f4b4d214a"
   }
}
Response Fields An object with the following keys:
NameTypeDescription
accountAddresscURL stringSDK AccountAddressThe Aptos address of created wallet.

​
wal_initializeWalletOnChain

Initializes a Shinami Invisible Wallet on the Aptos network the Gas Station rights of your access key is associated with (e.g. Mainnet). This comes after a call to wal_createWallet but is not always needed. That’s because:
  1. Initialization happens automatically if you send a transaction with an uninitialized wallet as the sender (e.g. calling wal_executeGaslessTransaction) .
  2. Also, if something is transferred to an address you control the keys for (e.g. an NFT) before you initialize it, you’ll still be able to control that NFT after you initialize it.
Access Key Requirements: In addition to Wallet Services rights, making this request requires an access key with Node Service and Gas Station rights for the Aptos network you wish to initialize the wallet on. This is because initialization involves submitting a basic transaction with the Invisible Wallet as the sender and the gas fee sponsored by your Gas Station fund. See how to make one here. See also the next section: Gas Station fund required: You need a Gas Station fund with APT in order to sponsorship transactions for an Invisible Wallet, including the transaction that explicitly initializes it on chain. For information on how to set this up, see the Aptos Gas Station FAQ page in our Help Center. Shinami sponsorship fees: See our Aptos Billing FAQ. Request Parameters
NameTypeDescription
walletIdstringA unique ID you maintain for the wallet. Can be based on your internal user IDs. Note: you cannot change this value in the future, so do not use a value that you or your users might change, such as a editable username.
sessionTokenstringThe token generated by shinami_key_createSession with the unalterable secret you will permanently associate with this walletId (and, ideally, only this walletId).
Example Request Template The TypeScript example uses the Shinami Clients SDK, which you can install with: 
npm install @shinami/clients
Replace all instances of {{name}} with the actual value for that name. 
curl https://api.us1.shinami.com/aptos/wallet/v1 \
-X POST \
-H 'X-API-Key: {{walletServicesAccessKey}}' \
-H 'Content-Type: application/json' \
-d '{
        "jsonrpc": "2.0",
        "method": "wal_initializeWalletOnChain",
        "params": [
            "{{walletId}}",
            "{{sessionToken}}"
        ],
        "id": 1
    }'
Example Response 
{
   "id" : 1,
   "jsonrpc" : "2.0",
   "result" : {
      "accountAddress" : "0x45329e69bf823b556ab930a244ab33e0a71f4065d52b4a763e51af2f4b4d214a"
   }
}
Response Fields An object with the following keys:
NameTypeDescription
accountAddresscURL stringSDK AccountAddressThe Aptos address of created wallet.

​
wal_createWalletOnChain

Creates and initializes a Shinami Invisible Wallet onto the Aptos chain. Generally, you can wait to initialize a wallet if you wish (see more in the description of wal_initializeWalletOnChain). We provide a variety of wallet creation and initialization methods to give you flexibility. Wallet creation limit On the free tier you have a limit of wallet creations per month as shown on the “Aptos 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. Access Key Requirements: In addition to Wallet Services rights, making this request requires an access key with Node Service rights and Gas Station rights for the Aptos network you wish to initialize the wallet on. This is because initialization involves submitting a basic transaction with the Invisible Wallet as the sender and the gas fee sponsored by your Gas Station fund. See how to make one here. See also the next section: Gas Station fund required: You need a Gas Station fund with APT in order to sponsorship transactions for an Invisible Wallet, including the transaction that explicitly initializes it on chain. For information on how to set this up, see the Aptos Gas Station FAQ page in our Help Center. Shinami sponsorship fees: See our Aptos Billing FAQ. Request Parameters
NameTypeDescription
walletIdstringA unique ID you maintain for the wallet. Can be based on your internal user IDs. Note: you cannot change this value in the future, so do not use a value that you or your users might change, such as a editable username.
sessionTokenstringThe token generated by shinami_key_createSession with the unalterable secret you will permanently associate with this walletId (and, ideally, only this walletId).
Example Request Template The TypeScript example uses the Shinami Clients SDK, which you can install with: 
npm install @shinami/clients
Replace all instances of {{name}} with the actual value for that name. 
curl https://api.us1.shinami.com/aptos/wallet/v1 \
-X POST \
-H 'X-API-Key: {{walletServicesAccessKey}}' \
-H 'Content-Type: application/json' \
-d '{
        "jsonrpc": "2.0",
        "method": "wal_createWalletOnChain",
        "params": [
            "{{walletId}}",
            "{{sessionToken}}"
        ],
        "id": 1
    }'
Example Response 
{
   "id" : 1,
   "jsonrpc" : "2.0",
   "result" : {
      "accountAddress" : "0x45329e69bf823b556ab930a244ab33e0a71f4065d52b4a763e51af2f4b4d214a"
   }
}
Response Fields An object with the following keys:
NameTypeDescription
accountAddresscURL stringSDK AccountAddressThe Aptos address of created wallet.

​
wal_getWallet

Gets the address of an existing Invisible Wallet, regardless of whether it is initialized or uninitialized on chain. Request Parameters
NameTypeDescription
walletIdstringA unique ID you maintain for the wallet. Can be based on your internal user IDs. Note: you cannot change this value in the future, so do not use a value that you or your users might change, such as a editable username.
Example Request Template The TypeScript example uses the Shinami Clients SDK, which you can install with:1 
npm install @shinami/clients
Replace all instances of {{name}} with the actual value for that name. 
curl https://api.us1.shinami.com/aptos/wallet/v1 \
-X POST \
-H 'X-API-Key: {{walletServicesAccessKey}}' \
-H 'Content-Type: application/json' \
-d '{
        "jsonrpc": "2.0",
        "method": "wal_getWallet",
        "params": [
            "{{walletId}}"
        ],
        "id": 1
    }'
Example Response 
{
   "id" : 1,
   "jsonrpc" : "2.0",
   "result" : {
      "accountAddress" : "0x45329e69bf823b556ab930a244ab33e0a71f4065d52b4a763e51af2f4b4d214a"
   }
}
Response Fields An object with the following keys:
NameTypeDescription
accountAddresscURL stringSDK AccountAddressThe Aptos address of created wallet.

​
wal_signTransaction

Use an initialized Shinami Invisible Wallet to sign a transaction. When the wallet is the sender and you are sponsoring as the feePayer, use wal_executeGaslessTransaction, which does all of: sign, sponsor, and submit the transaction to the Aptos network. Request Parameters
NameTypeDescription
walletIdstringA unique ID you maintain for the wallet. Can be based on your internal user IDs. Note: you cannot change this value in the future, so do not use a value that you or your users might change, such as a editable username.
sessionTokenstringThe token generated by shinami_key_createSession with the unalterable secret you will permanently associate with this walletId (and, ideally, only this walletId).
SDK-only
transaction		AnyRawTransactionA SimpleTransaction or a MultiAgentTransaction that does not have a fee payer. You can find an example of building a transaction in our tutorial
cURL-only
rawTransaction		Hex string | unsigned byte arrayBCS-serialized RawTransaction. Can be passed either as an unsigned byte array or a Hex string. For a Python example of how to serialize this to send to Shinami, see the Aptos Python SDK: rawTransaction tab of the Example Request Templates.
cURL-only
secondaryAddresses		string[](Optional) Required for multi-agent transactions. Array of addresses of the secondary signers for the transaction. Must be in the exact order.
cURL-only
feePayerAddress		string(Optional) Address of a feepayer for the rawTransaction.
Example Request Template The TypeScript example uses the Shinami Clients SDK, which you can install with: 
npm install @shinami/clients
Replace all instances of {{name}} with the actual value for that name. 
curl https://api.us1.shinami.com/aptos/wallet/v1 \
-X POST \
-H 'X-API-Key: {{walletServicesAccessKey}}' \
-H 'Content-Type: application/json' \
-d '{
        "jsonrpc": "2.0",
        "method": "wal_signTransaction",
        "params": [
            "{{walletId}}",
            "{{sessionToken}}",
            "{{rawTransaction}}",
            "{{(optional)secondardAddresses}}",
            "{{(optional)feePayerAddress}}"
        ],
        "id": 1
    }'
Example Response 
{
  "jsonrpc":"2.0",
  "result":{
    "signature":[0,32,136,128,248,41,24,171,70,49,247,26,7,233,63,120,178,130,84,171,58,188,184,203,137,23,210,92,89,62,182,10,55,2,64,239,224,55,68,196,84,93,88,60,245,168,112,48,199,204,225,105,109,15,6,64,145,58,175,225,89,230,38,71,179,223,193,212,114,240,142,212,165,123,209,71,50,202,29,114,133,212,40,240,123,38,189,76,4,208,237,156,135,159,154,143,122,206,9]
    ,
  "id":1
}
Response Fields Object with the following keys:
NameTypeDescription
signaturecURL Unsigned byte arraySDK AccountAuthenticatorThe Invisible Wallet’s signature for the transaction.
Notes for signing a non-sponsored transaction:
  • The Invisible wallet must be initialized on chain.
  • If you attempt to sign immediately after initializing a wallet you may get an error that the address was not found on chain, as it take a couple of seconds for the initialization to be processed by the Aptos blockchain.

​
wal_executeGaslessTransaction

Sponsors, signs, and executes a gasless transaction from a Shinami Invisible Wallet. This is a convenient end-to-end method for submitting sponsored transactions to the Aptos chain as opposed to doing all the steps individually. Access Key Requirements: In addition to Wallet Services rights, making this request requires an access key with Gas Station and Node Service rights for the Aptos network you wish to sponsor and execute the transaction on. See how to make one here. See also the next section: Gas Station fund required: You need a Gas Station fund with APT in order to sponsorship transactions for an Invisible Wallet. For information on how to set this up, see the Aptos Gas Station FAQ page in our Help Center. Shinami sponsorship fees: See our Aptos Billing FAQ. Request Parameters
NameTypeDescription
walletIdstringA unique ID you maintain for the wallet. Can be based on your internal user IDs. Note: you cannot change this value in the future, so do not use a value that you or your users might change, such as a editable username.
sessionTokenstringThe token generated by shinami_key_createSession with the unalterable secret you will permanently associate with this walletId (and, ideally, only this walletId).
SDK-only
transaction		AnyRawTransactionA SimpleTransaction or a MultiAgentTransaction. You can find an example of building a transaction in our tutorial
cURL-only
rawTransaction		Hex string | unsigned byte arrayBCS-serialized RawTransaction. Can be passed either as an unsigned byte array or a Hex string. For a Python example of how to serialize this to send to Shinami, see the Aptos Python SDK: rawTransaction tab of the Example Request Templates.
secondarySignersSDK AccountAuthenticator[]cURL [“address” : hex string, “signature”: BCS-serialized AccountAuthenticator(Can be passed either as an unsigned byte array or a hex string.)](optional) Array of additional signers and their signatures. Must be in the exact order. Required for multi-agent transactions.
Example Request Template The TypeScript example uses the Shinami Clients SDK, which you can install with: 
npm install @shinami/clients
Replace all instances of {{name}} with the actual value for that name. 
curl https://api.us1.shinami.com/aptos/wallet/v1 \
-X POST \
-H 'X-API-Key: {{walletServicesAccessKey}}' \
-H 'Content-Type: application/json' \
-d '{
        "jsonrpc": "2.0",
        "method": "wal_executeGaslessTransaction",
        "params": [
          "{{walletId}}",
          "{{sessionToken}}",
          "{{rawTransaction}}",
          [{
             "address": "{{secondarySignerOneAddress}}",
             "signature": "{{secondarySignerOneSignature}}"
          }]
        ],
        "id": 1
    }'
Example Response 
{
   "id" : 1,
   "jsonrpc" : "2.0",
   "result" : {
      "pendingTransaction" : {
         "expiration_timestamp_secs" : "1720213435",
         "gas_unit_price" : "150",
         "hash" : "0xfee720e44614f8164da7d58333ef3947abbe997e3ac10451ee9a56f9788d8e34",
         "max_gas_amount" : "200000",
         "payload" : {
            "arguments" : [
               "hello"
            ],
            "function" : "0xc13c3641ba3fc36e6a62f56e5a4b8a1f651dc5d9dc280bd349d5e4d0266d0817::message::set_message",
            "type" : "entry_function_payload",
            "type_arguments" : []
         },
         "sender" : "0x35d86428a7aee9863f9aa52d6aa4b583e2bcb7ee9d3e7d1cf1b6a7e13da503af",
         "sequence_number" : "4",
         "signature" : {
            "fee_payer_address" : "0x2cdcec66a48b596c923024102feda5ee759197fe844c5ba56013d3b9a99287b6",
            "fee_payer_signer" : {
               "public_key" : "0x57b9d494d31ed56f902362eef6e9d4fa8d22e390ab921bcb1678c8ec915ecbcf",
               "signature" : "0x1bb1186530bba89d8fa0d2706aba8d9908b11f7249f947e8833ecddd5dbb73f75fb8e325188631778d4ea4c8d10fafa03309f01b5373f1c5cac150b48bbddc09",
               "type" : "ed25519_signature"
            },
            "secondary_signer_addresses" : [],
            "secondary_signers" : [],
            "sender" : {
               "public_key" : "0x8880f82918ab4631f71a07e93f78b28254ab3abcb8cb8917d25c593eb60a3702",
               "signature" : "0xb67b702ab701bf88800a764639a495b11baf3d1df3553030e33f4ef92342d2962d867be5be2731cf6d3bbfe3281f99a641c9f900185c90787448d1284b2e7e0e",
               "type" : "ed25519_signature"
            },
            "type" : "fee_payer_signature"
         }
      }
   }
}
Response Fields Object with keys:
NameTypeDescription
pendingTransactioncURL object (same shape as a PendingTransactionResponse)SDK PendingTransactionResponseThe submitted transaction waiting in mempool.