> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nearnode.io/llms.txt
> Use this file to discover all available pages before exploring further.

# SDKs & Libraries

> Official client libraries for Node.js and Python. Community integrations for Go and Ruby.

NearNode provides official SDKs for the two most common integration languages. Every SDK is a thin, typed wrapper around the [REST API](/api-reference/introduction) — no magic, no vendor lock-in.

## Official SDKs

<CardGroup cols={2}>
  <Card title="Node.js / TypeScript" icon="js">
    Full TypeScript types. Works in Node.js 18+, Deno, and Bun.
  </Card>

  <Card title="Python" icon="python">
    Sync and async clients. Python 3.9+.
  </Card>
</CardGroup>

## Node.js

### Installation

```bash theme={null}
npm install @nearnode/sdk
```

### Quick Start

```javascript theme={null}
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:

```typescript theme={null}
import type { Node, Batch, AnalyticsEvent, RoutingRule } from '@nearnode/sdk';
```

## Python

### Installation

```bash theme={null}
pip install nearnode
```

### Quick Start

```python theme={null}
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:

<CodeGroup>
  ```bash cURL theme={null}
  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" }
    }'
  ```

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

  ```ruby Ruby theme={null}
  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) }
  ```
</CodeGroup>

## Community Integrations

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

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

## SDK Versioning

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

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

<Tip>
  Pin your SDK version in production. Subscribe to the [Changelog](/changelog) for breaking change announcements.
</Tip>