Gas Station API - Shinami Developer Documentation

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.us1.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 serverShinami 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

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. Important notes

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 .
Gas Station doesn’t support CORS, so you must send requests from your backend. For more info and some sample code, see our FE signing + BE sponsorship guide.
We charge a small fee (in SUI) per sponsorship request to cover our costs. For details, visit the “Sui Gas Station” tab on the Billing page of your Shinami dashboard.
You need to create a Gas Station fund in your Shinami dashboard before you 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. For how to do that and find the deposit address, see our Sui Gas Station Help Center page.
Auto vs manual budgeting: when you omit the gasBudget parameter, we set your gas budget automatically for you. We recommend this for most use cases. 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, and we’ll return these errors back to you, which should be the same as if you had made a sui_dryRunTransactionBlock request yourself. For more on auto vs manual budgeting, see the Appendix of our Gas Station tutorial.

Request Parameters: Shinami SDK

Name	Type	Description
tx	GaslessTransaction	Shinami `GaslessTransaction` interface with the following members (For a code example of building and sponsoring a transaction, see the Appendix):
tx.txKind	string	Base64 encoded, BCS serialized `TransactionKind`
tx.sender	string	Sui address of the `TransactionKind` sender
tx.gasBudget	string \| number	(Optional) The gas budget you wish to use for the transaction, in MIST. The transaction will fail if the gas cost exceeds this value. - If provided, we use the value as the budget of the sponsorship. - If omitted, we estimate the transaction cost for you. We then add a buffer (5% for non-shared objects, 25% for shared objects) and use that total value as the budget of the sponsorship.
tx.gasPrice	string \| number	(Optional) Gas price override. Must be equal to or greater than the current reference gas price. If omitted the current reference price is used. Under normal network conditions, the expectation is that this does not need to be set. For times of high network congestion, setting a gasPrice higher than the reference gas price gives your transaction higher priority. For more info, see Sui’s documentation on gas pricing.

Request Parameters: cURL

Name	Type	Description
transactionBytes	string	Base64 encoded, BCS serialized `TransactionKind`
sender	string	Sui address of the `TransactionKind` sender
gasBudget	string	(Optional) The gas budget you wish to use for the transaction, in MIST. The transaction will fail if the gas cost exceeds this value. - If provided, we use the value as the budget of the sponsorship. - If omitted, we estimate the transaction cost for you. We then add a buffer (5% for non-shared objects, 25% for shared objects) and use that total value as the budget of the sponsorship.
gasPrice	string	Optional gas price (must be equal to or greater than the current reference gas price). If omitted the current reference price is used. Under normal network conditions, the expectation is that this does not need to be set. For times of high network congestion, setting a gasPrice higher than the reference gas price gives your transaction higher priority. For more info, see Sui’s documentation on gas pricing.

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/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}}");

const sponsorshipData = 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

Name	Type	Description
txBytes	string	Base64 encoded, BCS serialized `TransactionData`, which now includes the gas sponsorship data.
txDigest	string	Base 58 encoded transaction digest. Store this and use it to call `gas_getSponsoredTransactionBlockStatus` defined below if needed.
signature	string	Base64 encoded transaction signature from the sponsor (your Gas Station fund wallet).
expireAtTime	int	Expiration time of the assigned gas object, in Unix epoch seconds. All sponsorships created with this method are set to expire one hour after creation.

gas_getSponsoredTransactionBlockStatus

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

Name	Type	Description
transactionDigest	String	Base58 encoded transaction digest (returned by gasSponsorTransactionBlock)

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/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
const status = await gas.getSponsoredTransactionStatus({{transactionDigest}});

Example Response

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

"IN_FLIGHT"

Possible Result Values

Name	Type	Description
”IN_FLIGHT”	String	A gas object has been assigned and its `expireAtTime` has not been reached. A transaction execution attempt has not been made.
”INVALID”	String	We did not find a gas object attached to the transaction that was sponsored by the fund this access key is tied to OR The gas object’s `expireAtTime` was reached and it is still unspent.
”COMPLETE”	String	A transaction execution attempt was made and the attached gas object was spent. This does not guarantee that the transaction was successfully executed.

gas_getFund

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, 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/sui/gas/v1 \
-X POST \
-H 'X-API-Key: YOUR_API_KEY' \
-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("YOUR_API_KEY");

const fundInfo = 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

Name	Type	Description
network	String	The network the fund is tied to.
name	String	The name given to the fund when it was created.
balance	Int	The balance of the fund, in MIST. (1,000,000,000 MIST = 1 SUI)
inFlight	Int	The amount we are currently withholding from your fund for active sponsorships, in MIST. This is what will be used to pay Sui transaction fees and Shinami fees for the sponsorship.
depositAddress	String \| null	`String` representing a Sui address if a deposit address has been created for the fund. `null` if no deposit address has been created. If you do not have a deposit address, follow the steps in the Sui Gas Station FAQ page of our Help Center and a deposit address will be automatically generated.

Appendix

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

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 { fromB64 } from "@mysten/sui/utils";
import { SuiClient, getFullnodeUrl } from "@mysten/sui/client";
import { GasStationClient, buildGaslessTransaction } from "@shinami/clients/sui";

// 2. Copy your Testnet Gas Station key value
const GAS_STATION_ACCESS_KEY = "KEY_VALUE";

// 3. Set up your Gas Station and Node Service clients. Here we're using the Mysten 
//     free Node Service, which is useful for testing but not production.
const nodeClient = new SuiClient({ url: getFullnodeUrl("testnet") });
const gasStationClient = new GasStationClient(GAS_STATION_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 { txBytes, signature: sponsorSignature } = await gasStationClient.sponsorTransaction(
  gaslessTx // by not setting gaslessTx.gasBudget we take
  //  advantage of Shinami auto-budgeting
);

// 7. Obtain the sender signature
const { signature: senderSignature } = await sender.signTransaction(fromB64(txBytes));

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

console.log(executeResponse);

​Overview

​Use Cases

​Authentication, Rate Limits, and Error Handling

​Send your first request

​Tutorials with E2E sample code

​Methods

​gas_sponsorTransactionBlock

​gas_getSponsoredTransactionBlockStatus

​gas_getFund

​Appendix

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

Overview

Use Cases

Authentication, Rate Limits, and Error Handling

Send your first request

Tutorials with E2E sample code

Methods

gas_sponsorTransactionBlock

gas_getSponsoredTransactionBlockStatus

gas_getFund

Appendix

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