> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://natural.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://natural.ferndocs.com/_mcp/server.

# SDKs

Natural provides official SDKs for building agents that interact with the Natural platform.

## Available tools

#### Python SDK

`pip install natural-sdk` — Build agents in Python

#### TypeScript SDK

`npm install @natural-co/sdk` — Build agents in TypeScript/JavaScript

#### Go SDK

`go get github.com/fern-demo/natural-go-sdk` — Build agents in Go

## Installation

**`Python`**

```bash title="Python"
pip install natural-sdk
# or
uv add natural-sdk
```

**`TypeScript`**

```bash title="TypeScript"
npm install @natural-co/sdk
# or
yarn add @natural-co/sdk
```

**`Go`**

```bash title="Go"
go get github.com/fern-demo/natural-go-sdk
```

## Quick start

**`Python`**

```python title="Python"
import os
from natural import NaturalClient

client = NaturalClient(token=os.environ["NATURAL_API_TOKEN"])

# Create a payment
payment = client.payments.create(
    idempotency_key="pay-invoice-1234",
    data={
        "attributes": {
            "amount": 10000,  # cents — $100.00
            "counterparty": {"type": "email", "value": "contractor@example.com"},
            "description": "Invoice #1234",
            "customerPartyId": "pty_019cd34e27c179bfbbe6870486b11b67",
        }
    },
)
print(payment.data.id)
```

**`TypeScript`**

```typescript title="TypeScript"
import { NaturalClient } from "@natural-co/sdk";

const client = new NaturalClient({ token: process.env.NATURAL_API_TOKEN });

// Create a payment
const payment = await client.payments.create({
    idempotencyKey: "pay-invoice-1234",
    data: {
        attributes: {
            amount: 10000, // cents — $100.00
            counterparty: { type: "email", value: "contractor@example.com" },
            description: "Invoice #1234",
            customerPartyId: "pty_019cd34e27c179bfbbe6870486b11b67",
        },
    },
});
console.log(payment.data.id);
```

**`Go`**

```go title="Go"
package main

import (
    "context"
    "fmt"
    "os"

    natural "github.com/fern-demo/natural-go-sdk"
    client "github.com/fern-demo/natural-go-sdk/client"
    option "github.com/fern-demo/natural-go-sdk/option"
)

func main() {
    c := client.NewNaturalClient(
        option.WithToken(os.Getenv("NATURAL_API_TOKEN")),
    )

    payment, err := c.Payments.Create(context.TODO(), &natural.CreatePaymentsRequest{
        IdempotencyKey: "pay-invoice-1234",
        Data: &natural.CreatePaymentsRequestData{
            Attributes: &natural.CreatePaymentsRequestDataAttributes{
                Amount:      10000, // cents — $100.00
                Description: natural.String("Invoice #1234"),
            },
        },
    })
    if err != nil {
        panic(err)
    }
    fmt.Println(payment.Data.Id)
}
```

## Agent authentication

Agents authenticate using Bearer tokens. When making payments on behalf of a customer, pass the agent ID and customer party ID:

**`Python`**

```python title="Python"
import os
from natural import NaturalClient

client = NaturalClient(
    token=os.environ["NATURAL_API_TOKEN"],
    agent_id="agt_019cd1798d637a4da75dce386343931d",
    instance_id="vendor-payouts-q1",
)

payment = client.payments.create(
    idempotency_key="vendor_payment_001",
    data={
        "attributes": {
            "amount": 50000,  # cents — $500.00
            "counterparty": {"type": "email", "value": "vendor@example.com"},
            "description": "Vendor payment",
            "customerPartyId": "pty_019cd34e27c27605a92edc2c7d1a5b34",
        }
    },
)
```

**`TypeScript`**

```typescript title="TypeScript"
import { NaturalClient } from "@natural-co/sdk";

const client = new NaturalClient({
    token: process.env.NATURAL_API_TOKEN,
    agentId: "agt_019cd1798d637a4da75dce386343931d",
    instanceId: "vendor-payouts-q1",
});

const payment = await client.payments.create({
    idempotencyKey: "vendor_payment_001",
    data: {
        attributes: {
            amount: 50000, // cents — $500.00
            counterparty: { type: "email", value: "vendor@example.com" },
            description: "Vendor payment",
            customerPartyId: "pty_019cd34e27c27605a92edc2c7d1a5b34",
        },
    },
});
```

## Available resources

Both SDKs provide these resources:

| Resource       | Description                        |
| -------------- | ---------------------------------- |
| `payments`     | Create and retrieve payments       |
| `wallet`       | Balance, deposits, and withdrawals |
| `transactions` | List transaction history           |
| `agents`       | Create and manage agents           |
| `customers`    | List customer relationships        |

## MCP server

Natural runs a hosted MCP server at `https://mcp.natural.co` for AI agent integration. Pick this path when an **AI host application** (Claude Code, Cursor, Codex) runs the agent — point the client at the endpoint and authenticate with OAuth. See [MCP](/guides/platform/mcp) for setup per client.

Use an SDK instead when you're running the agent runtime yourself.

## Related

* [REST API](/guides/platform/apis) — Direct HTTP access
* [CLI](/guides/platform/cli) — Command-line interface
* [MCP](/guides/platform/mcp) — AI agent integration