Skip to main content
Natural provides official SDKs for building agents that interact with the Natural platform.

​
Available tools

Python SDK

pip install naturalpay - Build agents in Python

TypeScript SDK

npm install @naturalpay/sdk - Build agents in TypeScript/JavaScript

​
Installation

pip install naturalpay
# or
uv add naturalpay

​
Quick start

from naturalpay import Natural

client = Natural()  # agent key from NATURAL_API_KEY

# Create a payment on behalf of a customer
payment = client.payments.create(
    amount=10000,  # cents - $100.00
    currency="USD",
    counterparty={"type": "email", "value": "contractor@example.com"},
    description="Invoice #1234",
    customer_party_id="pty_019cd34e27c179bfbbe6870486b11b67",
    x_instance_id="invoice-run-1234",
    idempotency_key="pay-invoice-1234",
)

print(payment.data.id)
print(payment.data.attributes.status)

​
Agent authentication

Both SDKs accept either credential type in NATURAL_API_KEY (see Authentication):
  • Agent key (ak_ntl_…) — bound to one agent. Requests resolve as that agent automatically: do not pass an agent ID (a conflicting one is rejected). instanceId is required on money-movement methods (payments.create, transfers, payment-request fulfillment) so each agent run is auditable.
  • API key (sk_ntl_…) — party-scoped. Calls act as your party. Prefer agent keys for new agent integrations.

​
With an agent key

# NATURAL_API_KEY=ak_ntl_prod_...
payment = client.payments.create(
    counterparty={"type": "email", "value": "vendor@example.com"},
    amount=50000,  # cents — $500.00
    description="Vendor payment",
    customer_party_id="pty_019cd34e27c27605a92edc2c7d1a5b34",
    x_instance_id="vendor-payouts-q1",  # required for money movement with an agent key
    idempotency_key="vendor_payment_001",
)

​
Available resources

Both SDKs provide these resources:
ResourceDescription
paymentsCreate and retrieve payments
walletBalance, deposits, and withdrawals
transactionsList transaction history
agentsCreate and manage agents
customersList 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.
  • MCP — Connect Claude, Cursor, and other AI hosts to Natural
  • CLI — For terminal and CI use
  • Dashboard — Onboarding and managing your account
  • REST API — Direct HTTP access to the Natural API