SDKs & Libraries

NearNode provides official SDKs for the two most common integration languages. Every SDK is a thin, typed wrapper around the REST API — no magic, no vendor lock-in.

Official SDKs

Node.js / TypeScript

Full TypeScript types. Works in Node.js 18+, Deno, and Bun.

Python

Sync and async clients. Python 3.9+.

Node.js

Installation

npm install @nearnode/sdk

Quick Start

import { NearNode } from '@nearnode/sdk';

const client = new NearNode({
  apiKey: process.env.NEARNODE_API_KEY,
});

// Create a node
const node = await client.nodes.create({
  label: 'Basel HQ Entrance',
  function_type: 'redirect',
  payload: { url: 'https://acme.com/checkin' },
});

console.log(node.url); // https://nearnode.io/v/r5v5z7t2

// List all nodes
const { data: nodes } = await client.nodes.list();

// Update a node
await client.nodes.update('r5v5z7t2', {
  payload: { url: 'https://acme.com/new-checkin' },
});

// Create a batch
const batch = await client.batches.create({
  label: 'Q1 2026 Cards',
  prefix: 'VID-2026',
  quantity: 100,
  function_type: 'vcard',
  base_payload: {
    organization: 'Acme Corp',
    website: 'https://acme.com',
  },
});

// Query analytics
const analytics = await client.analytics.query('r5v5z7t2', {
  period: '30d',
});

TypeScript Types

The SDK exports all request and response types:

import type { Node, Batch, AnalyticsEvent, RoutingRule } from '@nearnode/sdk';

Python

Installation

pip install nearnode

Quick Start

from nearnode import NearNode

client = NearNode(api_key="sk_live_...")

# Create a node
node = client.nodes.create(
    label="Basel HQ Entrance",
    function_type="redirect",
    payload={"url": "https://acme.com/checkin"},
)

print(node.url)  # https://nearnode.io/v/r5v5z7t2

# List all nodes
nodes = client.nodes.list()

# Update a node
client.nodes.update("r5v5z7t2", payload={"url": "https://acme.com/new-checkin"})

# Create a batch
batch = client.batches.create(
    label="Q1 2026 Cards",
    prefix="VID-2026",
    quantity=100,
    function_type="vcard",
    base_payload={
        "organization": "Acme Corp",
        "website": "https://acme.com",
    },
)

# Async support
import asyncio
from nearnode import AsyncNearNode

async def main():
    client = AsyncNearNode(api_key="sk_live_...")
    nodes = await client.nodes.list()

asyncio.run(main())

Direct API Access

No SDK required. The REST API works with any HTTP client:

curl -X POST https://nearnode.io/api/v1/nodes \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Basel HQ Entrance",
    "function_type": "redirect",
    "payload": { "url": "https://acme.com/checkin" }
  }'

req, _ := http.NewRequest("GET", "https://nearnode.io/api/v1/nodes", nil)
req.Header.Set("Authorization", "Bearer "+apiKey)
resp, _ := http.DefaultClient.Do(req)

require 'net/http'
require 'json'

uri = URI('https://nearnode.io/api/v1/nodes')
req = Net::HTTP::Get.new(uri)
req['Authorization'] = "Bearer #{ENV['NEARNODE_API_KEY']}"
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }

Community Integrations

Language	Package	Maintainer
Go	`go-nearnode`	Community
Ruby	`nearnode-ruby`	Community
PHP	`nearnode-php`	Community

Community SDKs are not officially supported. Use at your own discretion and verify compatibility with the current API version.

SDK Versioning

SDKs follow semantic versioning. Major versions correspond to API versions:

SDK Version	API Version	Status
`1.x`	`v1`	Current

Pin your SDK version in production. Subscribe to the Changelog for breaking change announcements.

Getting Started

Core Features

Developer Console

Enterprise Governance

Official SDKs

Node.js / TypeScript

Python

Node.js

Installation

Quick Start

TypeScript Types

Python

Installation

Quick Start

Direct API Access

Community Integrations

SDK Versioning

​Official SDKs

Node.js / TypeScript

Python

​Node.js

​Installation

​Quick Start

​TypeScript Types

​Python

​Installation

​Quick Start

​Direct API Access

​Community Integrations

​SDK Versioning

Official SDKs

Node.js

Installation

Quick Start

TypeScript Types

Python

Installation

Quick Start

Direct API Access

Community Integrations

SDK Versioning