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

> ## Agent Instructions
> When building application code, use `@naturalpay/sdk` for TypeScript or `naturalpay` for Python.
> When operating Natural directly for a user, use the payments MCP at `https://mcp.natural.com`.
> When searching Natural documentation, use the docs MCP at `https://docs.natural.com/mcp`.
> Use the Natural CLI for terminal and CI automation.
> Use REST only for unsupported languages or when the user explicitly requests raw HTTP.
> Start integration development and testing in the sandbox. Do not use production unless the user explicitly requests it.
> For sandbox requests that require `customerPartyId`, list customers first. Reuse only the intended fixture; otherwise create a customer.
> REST and SDK amounts use integer minor units. Payments MCP amounts use decimal strings with a required currency code.

# SDKs

> Client libraries for building agents with Natural

Natural has official SDKs for building agents, in Python and TypeScript.

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

  # Agent key from NATURAL_API_KEY; instance_id identifies this run.
  client = Natural(instance_id="invoice-run-1234")

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

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

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

  // One client per run: instanceId names the run, and the SDK sends it
  // as X-Instance-ID on every call this client makes.
  const client = new Natural({ instanceId: "invoice-run-1234" }); // 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: "ada@example.com" },
    description: "Invoice #1234",
    customerPartyId: "pty_019cd1798d627ad9bc302511c4f2c115",
    idempotencyKey: "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, so do not pass an agent ID (a conflicting one is rejected). An instance ID is required for money movement (payments and payment cancellation, Direct, transfers, deposits, withdrawals, and payment-request fulfillment) so each agent run is auditable. In Python, pass `instance_id` to the client constructor and build a client per run. In TypeScript, set it on the constructor or per call.
* **API key** (`sk_ntl_…`): Party-scoped. Calls act as your party and cannot act as an agent (see [Authentication](/api-reference/authentication#agent-keys)).

### With an agent key

<CodeGroup>
  ```python Python theme={null}
  # NATURAL_API_KEY=ak_ntl_prod_... (the agent's key)
  # One client per run: instance_id names the run, and the SDK sends it
  # as X-Instance-ID on every call this client makes.
  client = Natural(instance_id="vendor-payouts-q1")

  payment = client.payments.create(
      counterparty={"type": "email", "value": "ada@example.com"},
      amount=50000,  # cents ($500.00)
      description="Vendor payment",
      customer_party_id="pty_019cd1798d627ad9bc302511c4f2c115",
      idempotency_key="vendor_payment_001",
  )
  ```

  ```typescript TypeScript theme={null}
  // NATURAL_API_KEY=ak_ntl_prod_... (the agent's key)
  // One client per run: instanceId is required for money movement with an agent key.
  const client = new Natural({ instanceId: "vendor-payouts-q1" });

  const payment = await client.payments.create({
    counterparty: { type: "email", value: "ada@example.com" },
    amount: 50000, // cents ($500.00)
    description: "Vendor payment",
    customerPartyId: "pty_019cd1798d627ad9bc302511c4f2c115",
    idempotencyKey: "vendor_payment_001",
  });
  ```
</CodeGroup>

## Available resources

Both SDKs provide these resources. Python names them in snake\_case (`payment_requests`), TypeScript in camelCase (`paymentRequests`):

| Resource | Description |
| - | - |
| `payments` | Create, list, and cancel payments |
| `payment_requests` | Create, fulfill, and decline payment requests |
| `wallets` | Balances, wallet management, and agent attachment |
| `transfers` | Deposits, withdrawals, and internal transfers |
| `transactions` | List transaction history |
| `external_accounts` | Linked bank accounts |
| `agents` | Create and manage agents |
| `customers` | Customer relationships and invitations |
| `invitations` | Party invitations for teammates |
| `approvals` | Review and act on approval requests |
| `parties` | Party profile, limits, handle, and members |
| `api_keys` | Create and revoke API keys |
| `agent_keys` | Create, rotate, and revoke agent keys |
| `webhooks` | Webhook subscriptions |
| `events` | Published event history |
| `simulations` | Sandbox only: drive the counterparty side of test flows |

## Test in the sandbox

Both SDKs run against the [sandbox](/api-reference/sandbox/overview) unchanged: use a sandbox key and the sandbox base URL. The sandbox-only `simulations` resource drives the counterparty side of every flow.

<CodeGroup>
  ```python Python theme={null}
  # NATURAL_API_KEY=sk_ntl_sandbox_...
  client = Natural(base_url="https://api.sandbox.natural.com")
  ```

  ```typescript TypeScript theme={null}
  // NATURAL_API_KEY=sk_ntl_sandbox_...
  const client = new Natural({ baseUrl: "https://api.sandbox.natural.com" });
  ```
</CodeGroup>

See [Sandbox from MCP, CLI, and SDKs](/api-reference/sandbox/surfaces) for the full simulation surface.

## 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](/api-reference/about): Direct HTTP access to the Natural API


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.