Skip to main content
The NEAR API TypeScript library provides convenience functions for creating clients pre-configured for testnet and mainnet networks. These presets use carefully selected public RPC endpoints with good performance and reliability.

​
createTestnetClient

Creates a client configured for NEAR testnet with multiple public RPC endpoints.

​
Signature

function createTestnetClient(): Client

​
Returns

​
Client
Client
A Client instance configured for NEAR testnet

​
Configuration

The testnet client is configured with the following RPC endpoints: Regular endpoints:
  • https://test.rpc.fastnear.com - FastNEAR testnet RPC
  • https://rpc.testnet.near.org - Official NEAR testnet RPC
Archival endpoints:
  • https://neart.lava.build:443 - Lava testnet archival RPC

​
Example

import { createTestnetClient } from 'near-api-ts';

const client = createTestnetClient();

// Query testnet account
const accountInfo = await client.getAccountInfo({
  accountId: 'example.testnet'
});

console.log('Testnet account balance:', accountInfo.accountInfo.balance.total);

​
createMainnetClient

Creates a client configured for NEAR mainnet with multiple public RPC endpoints.

​
Signature

function createMainnetClient(): Client

​
Returns

​
Client
Client
A Client instance configured for NEAR mainnet

​
Configuration

The mainnet client is configured with the following RPC endpoints: Regular endpoints:
  • https://free.rpc.fastnear.com - FastNEAR mainnet RPC
  • https://rpc.intea.rs - Intear mainnet RPC
  • https://near.blockpi.network/v1/rpc/public - BlockPI mainnet RPC
Archival endpoints:
  • https://near.lava.build:443 - Lava mainnet archival RPC

​
Example

import { createMainnetClient } from 'near-api-ts';

const client = createMainnetClient();

// Query mainnet account
const accountInfo = await client.getAccountInfo({
  accountId: 'example.near'
});

console.log('Mainnet account balance:', accountInfo.accountInfo.balance.total);

​
Benefits of Presets

Quick Setup

Get started immediately without configuring RPC endpoints

Automatic Failover

Multiple endpoints provide redundancy and reliability

Optimized Performance

Carefully selected endpoints for best performance

Maintained

Endpoints are updated and maintained by the library

​
Comparing Presets vs Custom Configuration

import { createTestnetClient } from 'near-api-ts';

const client = createTestnetClient();
Advantages:
  • Zero configuration required
  • Multiple RPC endpoints for failover
  • Regularly updated with best endpoints
  • Sensible defaults for timeouts and retry behavior

​
Using Custom Configuration

import { createClient } from 'near-api-ts';

const client = createClient({
  transport: {
    rpcEndpoints: {
      regular: [{ url: 'https://your-custom-rpc.example.com' }]
    },
    policy: {
      timeouts: {
        requestMs: 60_000
      }
    }
  }
});
Use custom configuration when:
  • You have your own RPC infrastructure
  • You need custom headers (e.g., API keys)
  • You need different timeout or retry behavior
  • You’re using a private or custom NEAR network

​
Complete Examples

​
Testnet Development

import { createTestnetClient } from 'near-api-ts';

const client = createTestnetClient();

// Get account information
const account = await client.getAccountInfo({
  accountId: 'alice.testnet'
});

console.log('Account:', account.accountId);
console.log('Balance:', account.accountInfo.balance.available);
console.log('Storage used:', account.accountInfo.usedStorageBytes);

// Call a view function on a testnet contract
const greeting = await client.callContractReadFunction({
  contractAccountId: 'hello.testnet',
  functionName: 'get_greeting',
  functionArgs: { account_id: 'alice.testnet' }
});

console.log('Greeting:', greeting.result);

// Get latest block
const block = await client.getBlock();
console.log('Latest block height:', block.rawRpcResult.header.height);
console.log('Block hash:', block.rawRpcResult.header.hash);

​
Mainnet Production

import { createMainnetClient } from 'near-api-ts';

const client = createMainnetClient();

// Query mainnet contract
const nftMetadata = await client.callContractReadFunction({
  contractAccountId: 'nft-contract.near',
  functionName: 'nft_token',
  functionArgs: { token_id: '1' }
});

console.log('NFT metadata:', nftMetadata.result);

// Get account with error handling
const result = await client.safeGetAccountInfo({
  accountId: 'example.near'
});

if (result.ok) {
  console.log('Account found:', result.value.accountId);
  console.log('Balance:', result.value.accountInfo.balance.total);
} else {
  if (result.error.kind === 'Client.GetAccountInfo.Rpc.Account.NotFound') {
    console.log('Account does not exist');
  } else {
    console.error('Error:', result.error.kind);
  }
}

​
Environment-Based Selection

import { createTestnetClient, createMainnetClient } from 'near-api-ts';

const isProduction = process.env.NODE_ENV === 'production';
const client = isProduction ? createMainnetClient() : createTestnetClient();

console.log(`Connected to ${isProduction ? 'mainnet' : 'testnet'}`);

// Use the client
const block = await client.getBlock();
console.log('Current block height:', block.rawRpcResult.header.height);

​
Transport Policy

Both preset clients use the default transport policy: 
{
  rpcTypePreferences: ['Regular', 'Archival'],
  timeouts: {
    requestMs: 30_000,   // 30 seconds total
    attemptMs: 5_000     // 5 seconds per attempt
  },
  rpc: {
    maxAttempts: 2,
    retryBackoff: {
      minDelayMs: 100,
      maxDelayMs: 500,
      multiplier: 3
    }
  },
  failover: {
    maxRounds: 2,
    nextRpcDelayMs: 200,
    nextRoundDelayMs: 200
  }
}
This means:
  • Regular endpoints are tried first, then archival
  • Each RPC endpoint is retried up to 2 times with exponential backoff
  • The client will cycle through all endpoints up to 2 rounds
  • Individual attempts timeout after 5 seconds
  • Total request timeout is 30 seconds

​
When to Use Each Preset

​
Use createTestnetClient for:

Development

Building and testing your application

Testing

Running integration tests

Prototyping

Experimenting with new features

Learning

Learning NEAR development

​
Use createMainnetClient for:

Production

Live applications serving real users

Real Assets

Applications handling real NEAR tokens

Mainnet Data

Querying mainnet contracts and accounts

Analytics

Blockchain data analysis and indexing

​
Customizing Preset Clients

If you want to use a preset as a base but customize the transport policy, use the preset’s configuration as a starting point: 
import { createClient } from 'near-api-ts';

// Testnet with custom timeout
const client = createClient({
  transport: {
    rpcEndpoints: {
      regular: [
        { url: 'https://test.rpc.fastnear.com' },
        { url: 'https://rpc.testnet.near.org' }
      ],
      archival: [
        { url: 'https://neart.lava.build:443' }
      ]
    },
    policy: {
      timeouts: {
        requestMs: 60_000  // 60 seconds instead of 30
      }
    }
  }
});

Create Custom Client

Configure your own RPC endpoints and policies

Client Overview

Learn about Client methods and capabilities