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

Authentication, Rate Limits, and Error Handling

Authentication

See How to Send a Request below for service URLs and important info, as well as our Authentication and API Keys guide for how to create and edit API keys.

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. If you haven't assigned all the QPS you have for a network, or one key has more than it needs, you can adjust the rate limits of your keys to better balance your QPS allotment across your keys. You may also be able to reduce requests by using methods like sui_multiGetObjects instead of multiple calls to sui_getObject.

NOTE: Depending on your plan, you may also be subject to overall daily request limits. Hitting this limit will result result in a -32012, and you should not retry until the next day UTC. You can see your Node Service request totals in the Node Service Metrics section of your Shinami Dashboard. You can see your account limits on the "Sui Node Service" tab of the Billing page of your Shinami dashboard, where you can also upgrade your plan if needed.

Error Handling

See our Error Reference guide.

How to Send a Request

When sending a request to our Node Service:

Use the URL of the region you wish you send your requests to (see table below).
Send your access key in one of these two ways (done automatically by our TypeScript SDK):
1. A header (recommended for reduced visibility in logs, etc): "X-Api-Key: YOUR_ACCESS_KEY"
2. In the URL: e.g. https://api.us1.shinami.com/sui/node/v1/ACCESS_KEY
Use an access key from the same region as the URL you're using. Region URLs - us1 above - only work with API keys created in the same region. So, to use this API, you'll make Node Service API keys in our US East - us1 region.
Use an access key tied to the region and Sui network you want to interact with. When you create an API access key in your Shinami dashboard, you give it rights to exactly one network. We route to Mainnet or Testnet based on the API access key you send in the request. Note: Testnet is currently not offered in Tokyo, as shown in the table below.

Setting our Tokyo - apac1 Mainnet URL in our SDK

How to send to Tokyo - apac1 with our TypeScript SDK.

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

const shinamiAPACClient = createSuiClient(
	APAC_MAINNET_NODE_KEY,
	 "https://api.apac1.shinami.com/sui/node/v1/"
);

await shinamiAPACClient.getReferenceGasPrice();

Region table

Region name	Location	Networks offered	Service URL (same URL for all networks offered)	Only works with API keys made in
`US East - us1`	Eastern United States	Testnet, Mainnet	`https://api.us1.shinami.com/sui/node/v1`	`US East - us1`
`Tokyo - apac1`	Tokyo, Japan	Mainnet	`https://api.apac1.shinami.com/sui/node/v1`	`Tokyo - apac1`

Sample Request

Here is a quick sample request you can make using cURL, the Shinami Clients TypeScript SDK, the Mysten Rust SDK, or the Mysten TypeScript SDK. It's asking for the current reference price for gas on Testnet. We also show how to use Shinami with the Sui CLI for a different operation, in case you use that.

Because Testnet is currently only offered in our US East - us1 region, the sample code uses the service URL associated with that region: https://api.us1.shinami.com/sui/node/v1/. To send to Mainnet in our Tokyo - apac1 region, you would use an API key from that region and send to https://api.apac1.shinami.com/sui/node/v1/.

Example Request Template

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

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

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

const nodeClient = createSuiClient({{nodeTestnetAccessKey}});

await nodeClient.getReferenceGasPrice();

use sui_sdk::SuiClientBuilder;

#[tokio::main]
async fn main() -> Result<(), anyhow::Error> {

    let sui = SuiClientBuilder::default()
        .ws_url("wss://api.us1.shinami.com:443/sui/node/v1/{{nodeTestnetAccessKey}}")
        .build("https://api.us1.shinami.com:443/sui/node/v1/{{nodeTestnetAccessKey}}")
        .await?;

    let resp = sui.read_api().get_reference_gas_price().await?;
    println!("{}", resp);

    Ok(())
}

import { SuiClient } from '@mysten/sui/client';

const client = new SuiClient({ url: 'https://api.us1.shinami.com/sui/node/v1/NODE_API_ACCESS_KEY' });
await client.getReferenceGasPrice();

# Create a new env connecting to Shinami node service. It's tied to the
#  network (Testnet, Mainnet) that the API access key you use is tied to.
# Note that the faucet won't work with the Shinami URL set, so you may want
#  to ask for Testnet coins before switching to your Shinami env
sui client new-env \
  --alias shinami \
  --rpc https://api.us1.shinami.com:443/sui/node/v1/YOUR_NODE_API_KEY_WHICH_IS_TIED_TO_A_NETWORK \
  --ws wss://api.us1.shinami.com:443/sui/node/v1/YOUR_NODE_API_KEY_WHICH_IS_TIED_TO_A_NETWORK

# Activate the Shinami env
sui client switch --env shinami

# Ask for the gas coins owned by the address (with a suix_getOwnedObjects call to Shinami)
sui client gas

Example Response

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

// The reference gas price is 750 MIST, which is 0.00000075 SUI

750n // BigInt<u64>

// The reference gas price is 750 MIST, which is 0.00000075 SUI

750n // BigInt<u64>

// The reference gas price is 750 MIST, which is 0.00000075 SUI

╭────────────────────────────────────────────────────────────────────┬────────────────────┬──────────────────╮
│ gasCoinId                                                          │ mistBalance (MIST) │ suiBalance (SUI) │
├────────────────────────────────────────────────────────────────────┼────────────────────┼──────────────────┤
│ 0x447c1b7bc0a1499945aec4ad2822c67c000302903ade038d0933b54360ef92c1 │ 869604928          │ 0.86             │
│ 0x98badc4a11a7afc5629546859a7882832fbbc06a6b4240fe817e7db6d95f15a2 │ 1000000000         │ 1.00             │
│ 0xb7ca34fac3ef5bfe3a31fbf60cd9815aa91a88294920fe2d71dae3c2bcb91dd3 │ 1000000000         │ 1.00             │
│ 0xe3fafedeaf5e146eae2b809f07f3329fd612de257d78afce3fe585c2bc0d6e30 │ 1000000000         │ 1.00             │
╰────────────────────────────────────────────────────────────────────┴────────────────────┴──────────────────╯

For a detailed look at how Sui charges for transactions, see here. You can use Shinami's Gas Station to increase user engagement by sponsoring your users' transactions so they don't have to think about all those calculations.