Overview

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

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/node/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.

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

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, make sure to:

Set the URL to https://api.shinami.com/node/v1/
Send your access key in one of these two ways:
1. A header (recommended): "X-Api-Key: YOUR_ACCESS_KEY"
2. In the URL: https://api.shinami.com/node/v1/ACCESS_KEY
Use an access key tied to the 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.

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.

Example Request Template

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

curl https://api.shinami.com/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.shinami.com:443/node/v1/{{nodeTestnetAccessKey}}")
        .build("https://api.shinami.com:443/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.shinami.com/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.shinami.com:443/node/v1/YOUR_NODE_API_KEY_WHICH_IS_TIED_TO_A_NETWORK \
  --ws wss://api.shinami.com:443/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.