Skip to main content
Agents are created by developers using Natural to enable autonomous Payments workflows. Developers can use agents to request payment authority from their customers, represented by another Party. Developers can also use their own Party to send payments on behalf of themselves. A developer can register multiple agents on Natural, each of which can execute on behalf of multiple parties on Natural. Each agent-customer pair can have granular permissions and limits, managed through an agent-customer relationship requested by the developer and approved by the customer. Developers and their customers can subsequently update or revoke that relationship via the Dashboard or API.
Not building the agent runtime yourself? Connect Claude, Cursor, or another MCP client to Natural via the MCP connector with OAuth — the agent runs inside the host app and calls Natural’s tools directly.

​
Agent customer model

Alice (Developer) adds Bruce (Business) as a customer for one of her agents with specific permissions and limits. Bruce reviews and approves the agent-customer relationship: 
1. Alice (Developer)
   └─ Creates Agent (Carrier Payment Agent)
   └─ Adds Bruce as a customer for the agent
       └─ Permissions: [payments.create, payments.read]
       └─ Limit: $1000 per transaction

2. Bruce (Business)
   └─ Approves the agent-customer relationship

3. Alice (Developer)
   └─ Uses Agent to pay Terri (Contractor) on behalf of Bruce
Agent-customer relationships can include the following permissions:
  • payments.create - Create payments
  • payments.read - Read payment status
  • wallets.read - Check wallet balance
  • wallets.update - Modify wallet settings
  • party.read - View party information
  • party.update - Modify party details
Agents operate within a configurable per-transaction limit — the maximum amount for any single payment. When an agent attempts to exceed its limit, the transaction is blocked and an escalation is raised — the party’s owners and admins are notified by dashboard and email to approve or deny it. Developers do not need to store information around permissions, limits, and escalations.

​
Agent authentication

Agents authenticate via our 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 grants.
  • API keys (sk_ntl_…) — a party credential for user/party actions. Prefer agent keys or agent-scoped OAuth for new agent integrations.
See Authentication for the full credential model. Agent attribution is optional: dashboard users, user-scoped MCP grants, and plain API key calls move money as user/party actions without naming an agent.

​
Instance ID required for agent money movement

Whenever a money-movement request is attributed to an agent — by agent key or agent-scoped OAuth grant — it must also carry an instance_id (X-Instance-ID) for transaction observability. Agent-attributed money-movement requests without X-Instance-ID are rejected with a 400 error (missing_instance_id). Reads do not require an instance ID.

​
Agent instances

An instance_id is an identifier that groups related agent executions together. In other common frameworks like LangGraph or OpenAI Assistant API, this is represented by a thread_id. While Natural tracks every payment individually, an instance_id allows developers to correlate multiple actions belonging to the same logical workflow. For example, if your agent processes a multi-step payment execution (outbound contractors → negotiate rates → send multiple payment), you can tag all actions with the same instance_id to view them as a single workflow in the audit trail. Instances are developer-controlled. Developers should pass instance_id as an idempotent string to Natural that helps group their agent executions together.

​
Audit trail

All agent actions are logged and auditable, with clear grouping by requests and instances. These will include intents such as tool calls as well as internal execution mechanics such as limits being hit or escalations having been triggered. Developers can review agent activity to ensure compliance and detect anomalies.
  • Parties - Party identities that agents operate on behalf of
  • Users - Users who create and manage agents
  • Payments - Payment transactions executed by agents