Authorization: Bearer header. See Authentication. The same key works in the SDKs, the CLI, and as an MCP fallback. For AI hosts operating Natural for a user, prefer MCP with OAuth.
Environments
Use a key from the same environment as the base URL. Start in sandbox to test without moving real money.
Requests
To create or update a resource, wrap your fields indata.attributes. Omit type and id: the endpoint implies the type and Natural assigns the ID.
Creating a resource
This example creates a $50 sandbox payment from your party’s default wallet to the payment recipient fixture. SetNATURAL_API_KEY to a sandbox API key with payments.create permission. Your default wallet needs sufficient available funds. Amounts are in cents: 5000 means $50.00.
Idempotency-Key for each new payment. When retrying the same payment, reuse its key and request body within the 48-hour replay window.
See Create payment for all request fields and the response, and Error handling for failed requests.
Updating a resource
To update a resource, send aPATCH request with only the fields you want to change inside attributes. Omitted fields remain unchanged.
Responses
Responses follow the JSON:API specification. A response contains a single resource or a list of resources, and each resource has:type: A string identifying the kind of resource (e.g.,"agent","payment","transaction")id: A unique prefixed identifier (e.g.,agt_019cd179...,pay_019cd179...)attributes: The resource’s data fieldsrelationships(optional): Links to related resources
Single resource
Responses for a single resource wrap the resource in adata object:
List of resources
List endpoints return an array of resources indata, with pagination metadata in meta:
nextCursor value from meta.pagination to fetch subsequent pages.
Relationships
Relationships connect resources to each other without nesting the full related resource. Each relationship contains adata object with the related resource’s type and id.
Relationships appear in responses. In requests, reference related resources by including their ID directly in attributes (e.g., customerPartyId); the one exception is POST /agent-keys, which takes its agent as a request relationship.
To-one relationships
A to-one relationship links to a single related resource:null value in data indicates the relationship is absent:
Common relationships
Using relationship IDs
Use thetype and id from a relationship to fetch the related resource. For example, if a payment response includes:
Glossary
- Resource: An entity in the Natural API, such as a payment, agent, or transaction.
- Attribute: A piece of information about a resource (e.g.,
status,amount,createdAt). - Relationship: A link from one resource to another, represented by
typeandid.