TypeScript SDK

Full reference for the official Grat TypeScript and JavaScript client.

The TypeScript SDK is the primary way to interact with the Grat relay. It provides a type-safe interface for sponsoring transactions, simulating Soroban contract calls, and monitoring relay health.

Grat SDK is compatible with Stellar Protocol 26 (Yardstick). Fee estimation and Soroban simulation reflect the latest protocol changes.

Installation

npm

npm install @grat-official-sdk/sdk

Client Setup

Initialize the Grat client based on your target environment.

Testnet

import { Grat } from '@grat-official-sdk/sdk';

// Uses the default local relay at http://localhost:3000
const grat = Grat.testnet();

// Or specify a custom relay URL
const gratCustom = Grat.testnet('https://relay-testnet.yourdomain.com');

Constructor Configuration

If you need more control, you can use the standard constructor.

Parameter	Type	Default	Description
relayUrl	string	""	The full URL of your Grat relay server.
network	"testnet" | "mainnet"	"testnet"	The Stellar network passphrase to use.
apiKey	string	""	Your project’s API key (required for mainnet).
maxRetries	number	3	Maximum number of retries for failed requests.
timeout	number	30000	Request timeout in milliseconds.

Methods

sponsor(transaction)

Wraps a signed transaction in a fee-bump envelope and submits it to the network.

• Parameters: transaction: Transaction | FeeBumpTransaction
• Returns: Promise<SponsorResult>

const result = await grat.sponsor(tx);
console.log(result.hash);

sponsorContract(transaction)

An alias for sponsor, specifically labeled for Soroban smart contract transactions.

• Parameters: transaction: Transaction
• Returns: Promise<SponsorResult>

const result = await grat.sponsorContract(sorobanTx);

simulate(transaction)

Simulates a Soroban transaction to get resource fee estimates and diagnostic events.

• Parameters: transaction: Transaction
• Returns: Promise<SimulationResult>

const simulation = await grat.simulate(tx);
console.log(simulation.resourceFee);

estimate(transaction)

Returns estimated network fees (Classic and Soroban) for a given transaction.

• Parameters: transaction: Transaction | FeeBumpTransaction
• Returns: Promise<EstimateResult>

const fees = await grat.estimate(tx);

status()

Returns the health status and metadata of the connected relay server.

• Returns: Promise<HealthStatus>

const health = await grat.status();
console.log(health.status); // "ok"

Phase 2 Methods

The following methods are part of the Phase 2 Credit System and are currently under development.

• credits.balance(): Get the current credit balance for your API key.
• credits.history(): Retrieve a list of recent credit deposits and spend events.
• credits.depositInfo(): Get instructions for depositing XLM to top up your credits.
• transactions.list(): List all transactions sponsored by your API key.
• transactions.get(hash): Get detailed sponsorship metadata for a specific hash.

Response Types

SponsorResult

interface SponsorResult {
  hash: string;        // Transaction hash
  feePaid: string;     // Total fee paid in stroops
  ledger: number;      // Ledger number where tx was included
  resultXdr: string;   // Stellar result XDR
}

Error Handling

The SDK throws descriptive errors that can be caught and handled.

try {
  await grat.sponsor(tx);
} catch (error) {
  if (error instanceof GratError) {
    // Relay returned an error (e.g., 400, 429, 500)
    console.error(error.code, error.message);
  } else if (error instanceof NetworkError) {
    // Communication failure with the relay
    console.error("Network issue:", error.message);
  }
}

Automatic Retries

The SDK automatically retries requests that fail due to rate limiting (429) or temporary server issues (503). It uses exponential backoff to avoid overwhelming the relay. You can customize this behavior using the maxRetries option in the client configuration.

End-to-End Example: USDC Payment

import { Grat } from '@grat-official-sdk/sdk';
import { Keypair, Asset, TransactionBuilder, Networks, Operation } from '@stellar/stellar-sdk';

async function sendUSDC() {
  const grat = Grat.testnet();
  const senderKp = Keypair.fromSecret("SD...");
  const usdc = new Asset("USDC", "GB...");

  // 1. Build payment
  const tx = new TransactionBuilder(
    { publicKey: senderKp.publicKey(), sequence: "123" },
    { fee: "100", networkPassphrase: Networks.TESTNET }
  )
  .addOperation(Operation.payment({
    destination: "GC...",
    asset: usdc,
    amount: "50.00"
  }))
  .setTimeout(30)
  .build();

  // 2. Sign and Sponsor
  tx.sign(senderKp);
  const result = await grat.sponsor(tx);
  
  console.log("USDC Sent! Hash:", result.hash);
}

View on GitHub