Sui API: How to Choose the Right Interface for Your dApp

Sui's API landscape is changing. For years, developers interacted with the network through JSON-RPC, but the Sui Foundation has announced a deprecation timeline that makes gRPC and GraphQL the recommended paths forward. If you're searching for "sui api," you're likely trying to figure out which interface to use, how to connect, and what to do about the JSON-RPC sunset.

This guide cuts through the noise. You'll learn the differences between Sui's API interfaces, get practical code examples, and understand how to choose the right one for your project. We'll also show you how OnFinality's managed Sui infrastructure can simplify your access.

Decision Guide: Which Sui API Should You Use?

Before diving into details, here's a quick framework to help you decide which Sui API interface fits your needs:

If you're starting a new project, choose GraphQL or gRPC. JSON-RPC is deprecated and will be disabled on Sui Foundation mainnet full nodes by late July 2026. Building on a deprecated interface means you'll need to migrate soon.

If you have an existing JSON-RPC integration, plan your migration now. The timeline is clear: JSON-RPC will be disabled on Sui Foundation mainnet full nodes by the week of July 27, 2026, with full code removal by mid-October 2026. Start evaluating gRPC or GraphQL today.

If you need a managed solution, consider OnFinality. OnFinality provides reliable Sui RPC endpoints for both mainnet and testnet, handling the infrastructure so you can focus on building. Check our Sui network page for details.

Understanding Sui's API Interfaces

Sui offers three primary API interfaces, each with its own strengths:

JSON-RPC (Deprecated)

JSON-RPC has been the standard for interacting with Sui. It's a simple, HTTP-based protocol that uses JSON for requests and responses. Most existing Sui tools and SDKs use JSON-RPC.

Example JSON-RPC request:

curl -X POST https://rpc.sui.io \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "suix_getAllBalances",
    "params": ["0x94f1a597b4e8f709a396f7f6b1482bdcd65a673d111e49286c527fab7c2d0961"]
  }'

Why it's deprecated: The Sui Foundation is moving to more efficient and scalable protocols. JSON-RPC's limitations in streaming and performance led to this decision.

gRPC

gRPC is a high-performance, open-source RPC framework that uses Protocol Buffers for serialization. It supports bi-directional streaming, making it ideal for real-time data and high-throughput applications.

Example gRPC client (Node.js):

const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const packageDefinition = protoLoader.loadSync('sui.proto');
const suiProto = grpc.loadPackageDefinition(packageDefinition);

const client = new suiProto.sui.NodeService('https://rpc.sui.io', grpc.credentials.createSsl());

client.getLatestCheckpointSequenceNumber({}, (err, response) => {
  if (err) {
    console.error(err);
  } else {
    console.log('Latest checkpoint:', response);
  }
});

Why choose gRPC: It's designed for performance, with lower latency and higher throughput than JSON-RPC. It's also strongly typed, reducing errors.

GraphQL

GraphQL is a query language that allows clients to request exactly the data they need. It's ideal for frontend applications where you want to minimize data transfer and simplify client-side logic.

Example GraphQL query:

query {
  address(address: "0x94f1a597b4e8f709a396f7f6b1482bdcd65a673d111e49286c527fab7c2d0961") {
    balance
    coins {
      nodes {
        coinType
        balance
      }
    }
  }
}

Why choose GraphQL: It provides a flexible and efficient way to query on-chain data. You can fetch multiple resources in a single request, reducing network overhead.

Connecting to Sui with OnFinality

OnFinality provides managed Sui RPC endpoints for both mainnet and testnet. This means you don't have to run your own full node, and you get reliable, scalable access to the network.

Sui Mainnet RPC Endpoint:

https://rpc.sui.io

Sui Testnet RPC Endpoint:

https://rpc.testnet.sui.io

These endpoints support HTTP and WebSocket transports. For production applications, you'll want to use a dedicated endpoint with higher rate limits. Check our pricing page for details.

Code Examples: Making Your First Sui API Call

Let's walk through a simple example using JavaScript to fetch the balance of a Sui address.

Using JSON-RPC (Temporary)

const axios = require('axios');

const url = 'https://rpc.sui.io';
const address = '0x94f1a597b4e8f709a396f7f6b1482bdcd65a673d111e49286c527fab7c2d0961';

const payload = {
  jsonrpc: '2.0',
  id: 1,
  method: 'suix_getAllBalances',
  params: [address]
};

axios.post(url, payload)
  .then(response => {
    console.log(response.data.result);
  })
  .catch(error => {
    console.error(error);
  });

Using GraphQL (Recommended)

const axios = require('axios');

const url = 'https://rpc.sui.io/graphql';
const query = `
  query {
    address(address: "0x94f1a597b4e8f709a396f7f6b1482bdcd65a673d111e49286c527fab7c2d0961") {
      balance
    }
  }
`;

axios.post(url, { query })
  .then(response => {
    console.log(response.data.data);
  })
  .catch(error => {
    console.error(error);
  });

Common Pitfalls and How to Avoid Them

1. Using deprecated JSON-RPC for new projects. Avoid this. Start with GraphQL or gRPC to save yourself a migration later.
2. Not handling rate limits. Public endpoints have rate limits. For production, use a managed provider like OnFinality to get higher limits and dedicated resources.
3. Ignoring WebSocket support. For real-time updates (e.g., transaction notifications), use WebSocket. OnFinality supports WebSocket on its endpoints.
4. Forgetting about testnet. Always test your integration on testnet first. OnFinality provides a Sui testnet endpoint for this purpose.

Migration Path from JSON-RPC to gRPC or GraphQL

If you have an existing JSON-RPC integration, here's a step-by-step plan:

1. Audit your current usage. Identify which JSON-RPC methods you use and map them to gRPC or GraphQL equivalents.
2. Choose your target interface. For backend services, gRPC is often the best fit. For frontends, GraphQL is more flexible.
3. Set up a test environment. Use Sui testnet to experiment with the new interface.
4. Refactor your code. Update your SDKs and libraries. The Sui SDKs are being updated to support gRPC and GraphQL.
5. Test thoroughly. Ensure all functionality works as expected.
6. Deploy and monitor. Roll out the migration gradually, monitoring for errors.

Key Takeaways

• Sui offers three API interfaces: JSON-RPC (deprecated), gRPC, and GraphQL.
• JSON-RPC will be disabled by late July 2026, so plan your migration now.
• Choose gRPC for backend services and GraphQL for frontend applications.
• OnFinality provides managed Sui RPC endpoints for mainnet and testnet, simplifying your infrastructure.
• Always test on testnet before deploying to mainnet.

Frequently Asked Questions

What is the Sui API?

The Sui API refers to the set of interfaces that allow developers to interact with the Sui blockchain. It includes JSON-RPC, gRPC, and GraphQL.

Is JSON-RPC deprecated on Sui?

Yes, the Sui Foundation has announced that JSON-RPC will be deprecated and disabled on mainnet full nodes by late July 2026.

Which Sui API should I use?

For new projects, use GraphQL for frontend and gRPC for backend services. JSON-RPC is only suitable for temporary or legacy integrations.

Does OnFinality support Sui?

Yes, OnFinality provides managed Sui RPC endpoints for both mainnet and testnet. Visit our Sui network page for more information.

How do I get a Sui API key?

With OnFinality, you can sign up and get API keys for Sui endpoints. Check our pricing page for details.

What are the rate limits for Sui API?

Rate limits vary by provider and plan. OnFinality offers flexible plans with different rate limits. Contact us for specific details.

Can I use WebSocket with Sui API?

Yes, Sui supports WebSocket for real-time data. OnFinality endpoints support WebSocket connections.

How do I migrate from JSON-RPC to gRPC?

Follow the migration path outlined above. The Sui Foundation provides a JSON-RPC Migration Guide with detailed steps.

What is SuiJSON?

SuiJSON is a JSON-based format that aligns JSON inputs with Move call arguments. It has specific type coercion rules to ensure compatibility with Move types.

Where can I find the Sui API reference?

The official Sui API Reference provides complete documentation for JSON-RPC methods. For gRPC and GraphQL, refer to the Sui Documentation.