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

# Overview

> Autonomous actors that can move money

An agent (`agt_*`) is an actor that moves money for you or for customers who have authorized it. Create one to run autonomous [Payments](/guides/concepts/payments) workflows: an agent can pay on behalf of its creator, or on behalf of its creator's customers who have connected a wallet to it. Start with [Create an agent](/guides/agents/create-agent) and [`POST /agents`](/api-reference/agents/create-agent).

A developer can register many agents, and each agent can act for many parties. Every agent-customer pair carries its own permissions and limits: the developer requests them, the customer approves, and either side can update or revoke the relationship later through the dashboard or API.

## Agent customer model

Kendall (Developer) invites his customer to one of his agents with specific permissions and limits. Eric (Customer) reviews and approves the agent-customer relationship:

```text theme={null}
1. Kendall (Developer)
   └─ Creates Agent (Natural Bot)
   └─ Adds Eric as a customer for the agent
       └─ Permissions: [payments.create, payments.read]
       └─ Limit: $1000 per transaction

2. Eric (Customer)
   └─ Approves the agent-customer relationship

3. Kendall (Developer)
   └─ Uses Natural Bot to pay Klaire (Contractor) on behalf of Eric
```

Each relationship carries the permissions the customer granted and a per-transaction limit. A payment over the limit isn't rejected; it holds as an [Approval](/guides/concepts/approvals) for the party's owners or admins to approve or deny.

This invite-and-approve flow is **Connect**. Start with [Invite a customer](/guides/connect/invite-customer).

## Lifecycle

An agent is `ACTIVE` until you delete it with [`DELETE /agents/{agentId}`](/api-reference/agents/delete-agent), then `REVOKED`: it stops moving money at once, and the record stays readable.

## Agent authentication

Agents authenticate through the [SDKs](/guides/platform/sdks) using credentials the developer owns. There are two ways to establish agent identity:

* **Agent keys** (`ak_ntl_*`): A credential bound to one agent. Requests resolve as that agent automatically. The same verified binding applies to agent-scoped [MCP OAuth](/guides/platform/mcp) grants.
* **API keys** (`sk_ntl_*`): A party credential for user/party actions. It cannot act as an agent; see [Authentication](/api-reference/authentication#agent-keys).

See [Authentication](/api-reference/authentication) for the full credential model. Agent attribution is optional: dashboard users and plain API key calls move money as user/party actions without naming an agent.

## Agent attribution

Payments, payment requests, approvals, transfers, Direct ACH, wires, realtime payments, and transactions identify their initiating agent through `relationships.initiatorAgent`:

```json theme={null}
{
  "initiatorAgent": {
    "data": {
      "type": "agent",
      "id": "agt_00000000000000000000000000000001"
    }
  }
}
```

The relationship identifies the original initiating agent, including after approval, settlement, cancellation, or return. Its `data` is `null` for non-agent activity or when historical attribution is unavailable. Reading a resource as another agent does not change its attribution.

For a single-resource response, read `data.relationships.initiatorAgent`. For a list, read it on each item in `data`. The corresponding webhook resource uses `data.object.relationships.initiatorAgent`. Previously stored events retain their original payload on redelivery.

`recipientAgent` on payments and `payerAgent` on payment requests identify the addressed agent. They are separate from the initiating agent.

On a payment request, the initiator is the agent that created the request. The payment produced by fulfillment can have a different initiating agent. On an approval, attribution identifies the agent that requested the operation, not the person who approved it. Transactions retain the initiator of the underlying money movement.

## Agent instances

An instance ID (the `X-Instance-ID` header) groups related agent executions. Natural tracks every payment on its own, but an instance ID lets you tie the actions of one logical workflow together. You control the value: pass a stable string, up to 1024 characters, that identifies the run.

A money-movement request attributed to an agent (by agent key or agent-scoped OAuth grant) must send `X-Instance-ID`. This covers payments and their cancellation, payment-request fulfillment, Direct, deposits, withdrawals, and transfers; a request without it is rejected with 400 `missing_instance_id`. See [Authentication](/api-reference/authentication#agent-keys).


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