Overview

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

Use Cases

Shinami's Gas Station API lets you easily sponsor transactions for your users. SUI is pulled from a fund you create to power these transactions, managed in Shinami's dashboard (see a how to create a fund on the Sui Gas Station FAQ page of our Help Center).

Shinami facilitates sponsored transactions based on logic determined by you, the app developer. Examples include sponsoring each user's initial transaction(s) for better onboarding and sponsoring transactions of a particular type that you want to encourage.

Apps looking to onboard and retain Web2 users may choose to sponsor all transactions and use Gas Station alongside Shinami's app-controlled Invisible Wallets or user-controlled zkLogin wallets to make Web3 fully unseen. For a game, this allows players to focus on gameplay, while behind the scenes the game creates and modifies game assets in a Sui wallet designated for the player. Players get the benefits of Web3 without friction.

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/gas/v1/ACCESS_KEY. We recommend using a request header and not putting access keys in your request URLs for reduced visibility (in logs, etc).

For more information, including how to set up API access keys, see our Authentication and API Keys guide.

🚧

Call Shinami's Gas Station from your backend server

Shinami Gas Station does not support CORS requests, so you will get a CORS error if you make requests from your frontend. Use your backend server to integrate with Shinami's Gas Station. This limits exposure of your sponsorship access keys. If these keys are leaked, bad actors have the ability to sponsor transactions from your fund until it has been drained or you disable the key in our dashboard.

For an example flow of combining frontend signing and/or transaction inputs with backend sponsorship, see our Frontend signing + backend sponsorship tutorial.

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 consider batching multiple Move calls into a single programmable transaction block for sponsorship. They'll execute in sequence, having the same effect as if they were submitted separately. Finally, you can 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 Gas Station API.

Send your first request

For a quick sample request that doesn't require building a transaction, ask for the balance of the fund your access key is tied to with gas_getFund.

Tutorials with E2E sample code

Check out our TypeScript tutorial for more code samples and details on the end-to-end flow of creating, sponsoring, and executing a transaction. Also, since our Gas Station does not support CORS (browser) requests for security reasons, our Frontend signing + backend sponsorship tutorial .

Methods

gas_sponsorTransactionBlock

Description
Sponsor a gas-less transaction. This request takes two parts of a TransactionData object: the sender address and the programmable transaction block to be executed (with gas information is omitted, this is considered a TransactionKindobject). It asks the Gas Station to attach a gas object to it and produce a complete TransactionData object signed by the sponsor (your Gas Station fund). The returned TransactionData then needs to be signed by the sender and sent to Shinami's Node Service (or any full node) with both signatures to be executed with sui_executeTransactionBlock.

You cannot use the gas object in a sponsored transaction for other purposes: For example, you cannot write const [coin] = txb.splitCoins(txb.gas,[txb.pure(100)]); because it's accessing txb.gas. If you try to sponsor a TransactionKind that uses the gas object you will get a JSON-RPC -32602 error .

Shinami sponsorship fees: We charge a small fee (in SUI) per sponsorship request to cover our costs. For details, visit the Billing tab in your Shinami dashboard.

Access key creation and assignment: You'll need to create a network specific Gas Station fund in your Shinami dashboard before you can create an access key. When you create a gas station key, you assign it to a network (e.g. Testnet) and a fund on that network. If you're managing two apps on one network, each with their own Gas Station fund, the access key you use determines which fund is drawn from. See the Sui Gas Station FAQ page of our Help Center for how to set up a fund on Testnet and add free SUI to it if you don't have one.

Auto-budgeting notes

• As a part of auto-budgeting, we put your transactionBytes through a sui_dryRunTransactionBlock request as a free service before we attempt to sponsor it. This call will generate error messages for certain invalid transactions, such as if the transactionBytes are transferring an object that's not owned by the sender address you provide. We'll return these errors back to you, which should be the same as if you had made a sui_dryRunTransactionBlock request yourself. We do not do this step if you manually budget, so any issues that would be caught by sui_dryRunTransactionBlock will instead produce an error when you try to execute the transaction.
• In the time between sponsorship and execution, shared objects can change in a way that increases their transaction cost. Therefore, we encourage you to execute sponsored transactions quickly, if possible, to ensure that the sponsorship amount is sufficient. This is why we add a larger buffer on auto-budgeted sponsorships when a shared object is involved. While we believe this buffer will work in most cases, we encourage you to monitor the success rate of your auto-budgeted transactions to gauge whether your specific use-case requires manually setting an even larger gasBudget.

Request Parameters: Shinami SDK

Request Parameters: cURL

Example Request Template

The TypeScript example uses the Shinami Clients SDK.

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

  curl https://api.shinami.com/sui/gas/v1 \
  -X POST \
  -H 'X-API-Key: {{gasAccessKey}}' \
  -H 'Content-Type: application/json' \
  -d '{ 
          "jsonrpc":"2.0", 
          "method":"gas_sponsorTransactionBlock",
          "params":[
              "{{gaslessTransactionBytes}}",
              "{{senderAddress}}",
              "{{gasBudget}}",
              "{{gasPrice}}"
          ],
          "id":1
      }'

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

const gasClient = new GasStationClient("{{gasAccessKey}}");

await gasClient.sponsorTransaction(
    {{tx}} // if tx.gasBudget is omitted we use our auto-budgeting feature

Example Response

{
    "jsonrpc":"2.0",
    "result" :{
        "txBytes":"AAAAAQBCe5tpWnBOY2pjc+wz7B0Heo1Zj5cSbCJY3KWF60tybgljb2luX2ZsaXAKY2xhaW1fZmVlcwAAL44vPwjxyww1jOTrS7w8XpXnnhmIeecTKvuXScM6uIIBBqTsJrGuzKqeva+7IsFRCsYB7a6LpS34G1SEzn6DwSCoMHQAAAAAACCt2aRuz44LdsjRwsOpaPls3E4N7zVyDIT8AYWkinZQKh1jLUb/cEkQM/78TmOY3OqklD3PYlErTVc3i1q3A7xe6AMAAAAAAABAS0wAAAAAAAA=",
        "txDigest":"HvtKY9RwuE7NC4gLauLFPY3h5qepEy8R7aZHnc4gJu6G",
        "signature":"AAXr9gCHncXfpJiIuQLd1IyPCz/gIGebCeIFMkqollVsGfxVsoU1unAqOiQyvt4Xa18j/WC8dAN1pvf5Wsfnrw65rDp1CB4nXagWW48gUU79IRg3kJf+6erjnVYdenXh+A==",
        "expireAtTime":1695267721
    },
    "id":1
}

{
    "txBytes":"AAAAAQBCe5tpWnBOY2pjc+wz7B0Heo1Zj5cSbCJY3KWF60tybgljb2luX2ZsaXAKY2xhaW1fZmVlcwAAL44vPwjxyww1jOTrS7w8XpXnnhmIeecTKvuXScM6uIIBBqTsJrGuzKqeva+7IsFRCsYB7a6LpS34G1SEzn6DwSCoMHQAAAAAACCt2aRuz44LdsjRwsOpaPls3E4N7zVyDIT8AYWkinZQKh1jLUb/cEkQM/78TmOY3OqklD3PYlErTVc3i1q3A7xe6AMAAAAAAABAS0wAAAAAAAA=",
    "txDigest":"HvtKY9RwuE7NC4gLauLFPY3h5qepEy8R7aZHnc4gJu6G",
    "signature":"AAXr9gCHncXfpJiIuQLd1IyPCz/gIGebCeIFMkqollVsGfxVsoU1unAqOiQyvt4Xa18j/WC8dAN1pvf5Wsfnrw65rDp1CB4nXagWW48gUU79IRg3kJf+6erjnVYdenXh+A==",
    "expireAtTime":1695267721
}

Response Fields

gas_getSponsoredTransactionBlockStatus

Description
Check the status of a transaction you've sponsored to see if the gas object has been spent or not. Note that for many use cases, you will not need to check the status of your sponsorships. This is because when you get a successful response from the gas_sponsorTransactionBlock request, you will immediately obtain a sender signature and submit it to our Node Service for execution (and therefore you'll know the status).

Request Parameters

Example Request Template

The TypeScript example uses the Shinami Clients SDK.

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

curl https://api.shinami.com/sui/gas/v1 \
-X POST \
-H 'X-API-Key: {{gasAccessKey}}' \
-H 'Content-Type: application/json' \
-d '{ 
        "jsonrpc":"2.0", 
        "method":"gas_getSponsoredTransactionBlockStatus", 
        "params":[
            "{{transactionDigest}}"
        ], 
        "id":1
    }'

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

const gasClient = new GasStationClient("{{gasAccessKey}}");

// pass the digest returned by gas_sponsorTransactionBlock
await gas.getSponsoredTransactionStatus({{transactionDigest}});

Example Response

{
  	"jsonrpc":"2.0",
  	"result":"IN_FLIGHT",
  	"id":1
}

"IN_FLIGHT"

Possible Result Values

gas_getFund

Description

Get the balance for the Gas Station fund tied to the request's API access key. When you create a Gas Station access key, you link it to exactly one Gas Station fund. So, when you make this request, we return the balance for the fund that's tied to the access key you use for the request. To check which fund a Gas Station access key is tied too, see the Sui Gas Station FAQ page of our Help Center

Request Parameters

none

Example Request Template

The TypeScript example uses the Shinami Clients SDK.

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

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

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

const gasClient = new GasStationClient("{{gasAccessKey}}");

await gasClient.getFund();

Example Response

{
    "id" : 1,
    "jsonrpc" : "2.0",
    "result" : {
        "balance" : 4915573880,
        "depositAddress" : "0x73e9b9188e84fc642290cf84c5b774f78bb49b60327f8fba23ebc4c5cfaf028b",
        "inFlight" : 0,
        "name" : "First test fund",
        "network" : "SUI_TESTNET"
   }
}

{
  network: 'SUI_TESTNET',
  name: 'First test fund',
  balance: 4915573880,
  inFlight: 0,
  depositAddress: '0x73e9b9188e84fc642290cf84c5b774f78bb49b60327f8fba23ebc4c5cfaf028b'
}

Response Fields

Appendix

How to build, sponsor, sign, and execute a transaction

This section shows an example of how to build, sponsor, sign, and submit a transaction using the Shinami Clients SDK and the Mysten TypeScript SDK. For a high-level image of the sponsorship flow see here. For multiple end-to-end examples, see our Gas Station TypeScript tutorial.

Key requirements

1. When you prepare a transaction for sponsorship, make you prepare a TransactionKind, which is a transaction without the gas information (since this will be assigned by our Gas Station). When you make the build() call on your Transaction, make sure that onlyTransactionKind: true. In the code below, our SDK's buildGaslessTransaction function does this behind the scenes.

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

// 1. Import everything you need
import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";
import { Transaction } from "@mysten/sui/transactions";
import { 
  GasStationClient, createSuiClient, buildGaslessTransaction 
} from "@shinami/clients/sui";

// 2. Copy your Testnet Gas Station and Node Service key value
const GAS_AND_NODE_TESTNET_ACCESS_KEY = "{{gasAndNodeServiceTestnetAccessKey}}";

// 3. Set up your Gas Station and Node Service clients
const nodeClient = createSuiClient(GAS_AND_NODE_TESTNET_ACCESS_KEY);
const gasStationClient = new GasStationClient(GAS_AND_NODE_TESTNET_ACCESS_KEY);

// 4. Generate a sender. In production, you won't be using a newly generated sender 
//  each time. The sender will often be a wallet the user connected or an embedded
//  wallet you control for the user. This just makes for a shorter example.
const sender = new Ed25519Keypair();

// 5. Build a GaslessTransaction
const gaslessTx = await buildGaslessTransaction(
  (txb) => {
    txb.moveCall({
      target: "0xfa0e78030bd16672174c2d6cc4cd5d1d1423d03c28a74909b2a148eda8bcca16::clock::access",
      arguments: [txb.object('0x6')],
    });   
  },
  { sui: nodeClient }
  );

// 6. Set the sender address and ask for a sponsorship
gaslessTx.sender = sender.toSuiAddress();
const sponsoredResponse = await gasStationClient.sponsorTransaction(
    gaslessTx // by not setting gaslessTx.gasBudget we take 
              //  advantage of Shinami auto-budgeting
  );

// 7. Obtain the sender signature
const senderSig = await Transaction.from(sponsoredResponse?.txBytes).sign(
{ signer: sender }
);

// 8. Submit the transaction, along with the sender and sponsor signatures
const executeResponse = await nodeClient.executeTransactionBlock({
    transactionBlock: sponsoredResponse?.txBytes,
    signature: [senderSig?.signature, sponsoredResponse?.signature]
  });