SDKs | Natural Docs

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

pip install natural-sdk
# or
uv add natural-sdk

Quick start

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)

Agent authentication

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

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",
        }
    },
)

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 for setup per client.

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

REST API — Direct HTTP access
CLI — Command-line interface
MCP — AI agent integration