createClient

Create a custom NEAR API client with your own RPC endpoints and transport policies

createClient creates a new Client instance with custom configuration. This gives you full control over RPC endpoints, retry behavior, timeouts, and failover strategies.

Signature

function createClient(args: CreateClientArgs): Client

Parameters

args · CreateClientArgs · required

Configuration for the client

Show properties

transport · CreateTransportArgs · required

Transport configuration including RPC endpoints and policies

Show properties

rpcEndpoints · RpcEndpoints · required

RPC endpoint configuration

Show properties

regular · RpcEndpoint[]

Regular (non-archival) RPC endpoints

archival · RpcEndpoint[]

Archival RPC endpoints for historical data

You must provide at least one of regular or archival endpoints.

policy · PartialTransportPolicy

Transport policy configuration (timeouts, retries, failover)

Show properties

rpcTypePreferences · RpcTypePreferences

Preferred order of RPC types to try. Options:

• ['Regular', 'Archival'] - Try regular first, then archival (default)
• ['Archival', 'Regular'] - Try archival first, then regular
• ['Regular'] - Only use regular endpoints
• ['Archival'] - Only use archival endpoints

timeouts · object

Timeout configuration

Show properties

requestMs · number

Total request timeout in milliseconds (default: 30000)

attemptMs · number

Individual attempt timeout in milliseconds (default: 5000)

rpc · object

RPC retry configuration

Show properties

maxAttempts · number

Maximum retry attempts per RPC endpoint (default: 2)

retryBackoff · object

Exponential backoff configuration

Show properties

minDelayMs · number

Minimum delay between retries in milliseconds (default: 100)

maxDelayMs · number

Maximum delay between retries in milliseconds (default: 500)

multiplier · number

Backoff multiplier (default: 3)

failover · object

Failover configuration

Show properties

maxRounds · number

Maximum rounds through all RPC endpoints (default: 2)

nextRpcDelayMs · number

Delay before trying next RPC endpoint in milliseconds (default: 200)

nextRoundDelayMs · number

Delay before starting next round in milliseconds (default: 200)

Returns

Client · Client

A fully configured Client instance with all methods available

RpcEndpoint Type

type RpcEndpoint = {
  url: string;
  headers?: Record<string, string>;
};

url · string · required

The RPC endpoint URL

headers · Record<string, string>

Custom HTTP headers to include with requests (e.g., API keys)

Examples

Basic Configuration

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

const client = createClient({
  transport: {
    rpcEndpoints: {
      regular: [
        { url: 'https://rpc.testnet.near.org' }
      ]
    }
  }
});

Multiple Endpoints with Failover

const client = createClient({
  transport: {
    rpcEndpoints: {
      regular: [
        { url: 'https://test.rpc.fastnear.com' },
        { url: 'https://rpc.testnet.near.org' }
      ],
      archival: [
        { url: 'https://archival-rpc.testnet.near.org' }
      ]
    }
  }
});

Custom Headers (API Keys)

const client = createClient({
  transport: {
    rpcEndpoints: {
      regular: [
        {
          url: 'https://near-testnet.infura.io/v3/YOUR_PROJECT_ID',
          headers: {
            'Authorization': 'Bearer YOUR_API_KEY'
          }
        }
      ]
    }
  }
});

Custom Transport Policy

const client = createClient({
  transport: {
    rpcEndpoints: {
      regular: [{ url: 'https://rpc.testnet.near.org' }],
      archival: [{ url: 'https://archival-rpc.testnet.near.org' }]
    },
    policy: {
      // Prefer archival endpoints
      rpcTypePreferences: ['Archival', 'Regular'],
      
      // Increase timeouts for slow networks
      timeouts: {
        requestMs: 60_000,  // 60 seconds
        attemptMs: 10_000   // 10 seconds
      },
      
      // More aggressive retries
      rpc: {
        maxAttempts: 3,
        retryBackoff: {
          minDelayMs: 200,
          maxDelayMs: 1000,
          multiplier: 2
        }
      },
      
      // More failover rounds
      failover: {
        maxRounds: 3,
        nextRpcDelayMs: 100,
        nextRoundDelayMs: 500
      }
    }
  }
});

Archival-Only Configuration

const client = createClient({
  transport: {
    rpcEndpoints: {
      archival: [{ url: 'https://archival-rpc.testnet.near.org' }]
    },
    policy: {
      rpcTypePreferences: ['Archival']
    }
  }
});

Default Transport Policy

If you don’t provide a custom policy, the following defaults are used:

{
  rpcTypePreferences: ['Regular', 'Archival'],
  timeouts: {
    requestMs: 30_000,   // 30 seconds
    attemptMs: 5_000     // 5 seconds
  },
  rpc: {
    maxAttempts: 2,
    retryBackoff: {
      minDelayMs: 100,
      maxDelayMs: 500,
      multiplier: 3
    }
  },
  failover: {
    maxRounds: 2,
    nextRpcDelayMs: 200,
    nextRoundDelayMs: 200
  }
}

Error Handling

The createClient function throws if:

• Invalid arguments are provided (fails schema validation)
• An internal error occurs during client initialization

try {
  const client = createClient({
    transport: {
      rpcEndpoints: {
        regular: [{ url: 'https://rpc.testnet.near.org' }]
      }
    }
  });
} catch (error) {
  if (error.kind === 'CreateClient.Args.InvalidSchema') {
    console.error('Invalid configuration:', error.context.zodError);
  } else if (error.kind === 'CreateClient.Internal') {
    console.error('Internal error:', error.context.cause);
  }
}

Safe Variant

For applications that prefer Result types over exceptions, use safeCreateClient:

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

const result = safeCreateClient({
  transport: {
    rpcEndpoints: {
      regular: [{ url: 'https://rpc.testnet.near.org' }]
    }
  }
});

if (result.ok) {
  const client = result.value;
  // Use client
} else {
  console.error('Failed to create client:', result.error);
}

Related

Network Presets

Use pre-configured clients for testnet and mainnet

Client Overview

Learn about Client methods and capabilities