Skip to main content
An agent (agt_*) is an actor that moves money for you or for customers who have authorized it. Create one to run autonomous 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 and POST /agents. 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:
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 for the party’s owners or admins to approve or deny. This invite-and-approve flow is Connect. Start with Invite a customer.

​
Lifecycle

An agent is ACTIVE until you delete it with DELETE /agents/{agentId}, then REVOKED: it stops moving money at once, and the record stays readable.

​
Agent authentication

Agents authenticate through the 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. It cannot act as an agent; see Authentication.
See 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:
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.