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

# SDKs

> Client libraries for building agents with Natural

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

## Available tools

<CardGroup cols={2}>
  <Card title="Python SDK" icon="python">
    `pip install naturalpay` - Build agents in Python
  </Card>

  <Card title="TypeScript SDK" icon="js">
    `npm install @naturalpay/sdk` - Build agents in TypeScript/JavaScript
  </Card>
</CardGroup>

## Installation

<CodeGroup>
  ```bash Python theme={null}
  pip install naturalpay
  # or
  uv add naturalpay
  ```

  ```bash TypeScript theme={null}
  npm install @naturalpay/sdk
  # or
  yarn add @naturalpay/sdk
  ```
</CodeGroup>

## Quick start

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

  ```typescript TypeScript theme={null}
  import Natural from "@naturalpay/sdk";

  const client = new Natural(); // agent key from NATURAL_API_KEY

  // Create a payment on behalf of a customer
  const payment = await client.payments.create({
    amount: 10000, // cents - $100.00
    currency: "USD",
    counterparty: { type: "email", value: "contractor@example.com" },
    description: "Invoice #1234",
    customerPartyId: "pty_019cd34e27c179bfbbe6870486b11b67",
    "X-Instance-ID": "invoice-run-1234",
    "Idempotency-Key": "pay-invoice-1234",
  });

  console.log(payment.data.id);
  console.log(payment.data.attributes.status);
  ```
</CodeGroup>

## Agent authentication

Both SDKs accept either credential type in `NATURAL_API_KEY` (see [Authentication](/api-reference/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

<CodeGroup>
  ```python Python theme={null}
  # 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",
  )
  ```

  ```typescript TypeScript theme={null}
  // NATURAL_API_KEY=ak_ntl_prod_...
  const payment = await client.payments.create({
    counterparty: { type: "email", value: "vendor@example.com" },
    amount: 50000, // cents — $500.00
    description: "Vendor payment",
    customerPartyId: "pty_019cd34e27c27605a92edc2c7d1a5b34",
    "X-Instance-ID": "vendor-payouts-q1", // required for money movement with an agent key
    "Idempotency-Key": "vendor_payment_001",
  });
  ```
</CodeGroup>

## 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

* [MCP](/guides/platform/mcp) — Connect Claude, Cursor, and other AI hosts to Natural
* [CLI](/guides/platform/cli) — For terminal and CI use
* [Dashboard](/guides/platform/dashboard) — Onboarding and managing your account
* [REST API](/guides/platform/apis) — Direct HTTP access to the Natural API