OpenAPI Specification
openapi: 3.1.1
info:
title: Natural Agent Keys Payments API
version: 0.2.0
description: 'Natural''s payments API for autonomous agents.
**Base URL:** `https://api.natural.com`
AI agents, including coding agents, should prefer the hosted MCP server at `https://mcp.natural.com` when an MCP-aware host runs the agent, the Natural CLI for terminal/CI workflows, and the official SDKs for application runtimes they own. Use direct HTTP only for explicit low-level integrations, unsupported SDK gaps, or infrastructure work where REST is required.
For support: support@natural.com'
servers:
- url: https://api.natural.com
description: Production
tags:
- name: Payments
description: Payment management
paths:
/payments:
post:
operationId: payments.create
summary: Create payment
description: Create a payment
tags:
- Payments
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
attributes:
type: object
properties:
amount:
type: integer
exclusiveMinimum: 0
description: Amount in cents.
counterparty:
anyOf:
- type: object
properties:
type:
type: string
enum:
- email
value:
type: string
maxLength: 254
format: email
description: Email address.
required:
- type
- value
additionalProperties: false
- type: object
properties:
type:
type: string
enum:
- phone
value:
type: string
maxLength: 16
description: Phone number.
required:
- type
- value
additionalProperties: false
- type: object
properties:
type:
type: string
enum:
- party_id
value:
type: string
pattern: ^pty_[0-9a-f]{32}$
description: Natural party ID (pty_*).
required:
- type
- value
additionalProperties: false
- type: object
properties:
type:
type: string
enum:
- agent_id
value:
type: string
pattern: ^agt_[0-9a-f]{32}$
description: Natural agent ID (agt_*).
required:
- type
- value
additionalProperties: false
- type: object
properties:
type:
type: string
enum:
- handle
value:
type: string
maxLength: 62
description: Natural handle (@handle or @handle-slug).
required:
- type
- value
additionalProperties: false
title: PaymentRecipientCounterparty
description: Payment recipient. Agent recipients use their preferred wallet or their party's default wallet.
customerPartyId:
type: string
pattern: ^pty_[0-9a-f]{32}$
description: Sender party ID (pty_*). Omit to send from your own wallet; provide for delegated payments on behalf of a customer.
currency:
enum:
- USD
type: string
default: USD
description: Currency code.
description:
type: string
maxLength: 80
description: Payment description. Maximum 80 characters.
walletId:
type: string
pattern: ^wal_[0-9a-f]{32}$
description: Source wallet ID (wal_*). Omit to pay from the sender party's default wallet.
required:
- amount
- counterparty
additionalProperties: false
title: PaymentCreateAttributes
required:
- attributes
additionalProperties: false
required:
- data
additionalProperties: false
title: PaymentCreateRequest
examples:
default:
summary: Default
value:
data:
attributes:
amount: 500000
currency: USD
counterparty:
type: party_id
value: pty_019cd1798d627ad9bc302511c4f2c115
customerPartyId: pty_019cd1798d617f65a79cb965dda9eac3
description: Payment for Q4 2025 development work
responses:
'201':
description: Successful Response
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
type:
type: string
enum:
- payment
id:
type: string
pattern: ^pay_[0-9a-f]{32}$
attributes:
type: object
properties:
amount:
type: integer
description: Amount in cents.
currency:
type: string
description: Currency code.
status:
enum:
- CREATED
- PROCESSING
- PENDING_CLAIM
- IN_REVIEW
- COMPLETED
- FAILED
- RETURNED
- APPROVAL_DENIED
- CANCELED
type: string
description: Payment status.
description:
anyOf:
- type: string
- type: 'null'
description: Payment description.
createdAt:
type: string
description: When this payment was created.
updatedAt:
anyOf:
- type: string
- type: 'null'
description: When this payment was last updated.
required:
- amount
- currency
- status
- description
- createdAt
- updatedAt
additionalProperties: false
title: PaymentAttributes
relationships:
type: object
properties:
sender:
type: object
properties:
data:
anyOf:
- type: object
properties:
type:
type: string
enum:
- party
id:
type: string
pattern: ^pty_[0-9a-f]{32}$
required:
- type
- id
additionalProperties: false
title: ResourceIdentifier
description: Related resource identifier.
- type: 'null'
required:
- data
additionalProperties: false
title: NullableToOneRelationship
description: Party that initiated the payment, when the sender is on Natural.
senderAgent:
type: object
properties:
data:
anyOf:
- type: object
properties:
type:
type: string
enum:
- agent
id:
type: string
pattern: ^agt_[0-9a-f]{32}$
required:
- type
- id
additionalProperties: false
title: ResourceIdentifier
description: Related resource identifier.
- type: 'null'
required:
- data
additionalProperties: false
title: NullableToOneRelationship
description: Sending agent, or null when the payment was not sent by an agent.
recipient:
type: object
properties:
data:
anyOf:
- type: object
properties:
type:
type: string
enum:
- party
id:
type: string
pattern: ^pty_[0-9a-f]{32}$
required:
- type
- id
additionalProperties: false
title: ResourceIdentifier
description: Related resource identifier.
- type: 'null'
required:
- data
additionalProperties: false
title: NullableToOneRelationship
description: Recipient party for this payment, when known.
recipientAgent:
type: object
properties:
data:
anyOf:
- type: object
properties:
type:
type: string
enum:
- agent
id:
type: string
pattern: ^agt_[0-9a-f]{32}$
required:
- type
- id
additionalProperties: false
title: ResourceIdentifier
description: Related resource identifier.
- type: 'null'
required:
- data
additionalProperties: false
title: NullableToOneRelationship
description: Recipient agent, or null unless addressed by agent ID or agent handle.
transaction:
type: object
properties:
data:
anyOf:
- type: object
properties:
type:
type: string
enum:
- transaction
id:
type: string
required:
- type
- id
additionalProperties: false
title: ResourceIdentifier
description: Related resource identifier.
- type: 'null'
required:
- data
additionalProperties: false
title: NullableToOneRelationship
description: Sender-side transaction for this payment, when available.
paymentRequest:
type: object
properties:
data:
anyOf:
- type: object
properties:
type:
type: string
enum:
- paymentRequest
id:
type: string
pattern: ^prq_[0-9a-f]{32}$
required:
- type
- id
additionalProperties: false
title: ResourceIdentifier
description: Related resource identifier.
- type: 'null'
required:
- data
additionalProperties: false
title: NullableToOneRelationship
description: Payment request that produced this payment, when applicable.
required:
- sender
- senderAgent
- recipient
- recipientAgent
- transaction
- paymentRequest
additionalProperties: false
title: PaymentRelationships
required:
- type
- id
- attributes
- relationships
additionalProperties: false
title: PaymentResource
required:
- data
additionalProperties: false
title: PaymentResponse
examples:
default:
summary: Default
value:
data:
type: payment
id: pay_550e8400e29b41d4a716446655440000
attributes:
amount: 500000
currency: USD
status: PROCESSING
description: Payment for Q4 2025 development work
createdAt: '2026-01-04T15:30:00Z'
updatedAt: '2026-01-04T15:30:00Z'
relationships:
sender:
data:
type: party
id: pty_019cd1798d617f65a79cb965dda9eac3
senderAgent:
data: null
recipient:
data:
type: party
id: pty_019cd1798d627ad9bc302511c4f2c115
recipientAgent:
data: null
transaction:
data:
type: transaction
id: txn_550e8400e29b41d4a716446655440000
paymentRequest:
data: null
headers:
X-RateLimit-Limit:
description: Maximum requests allowed per window.
schema:
type: integer
X-RateLimit-Remaining:
description: Requests remaining in current window.
schema:
type: integer
X-RateLimit-Reset:
description: Unix timestamp when rate limit resets.
schema:
type: integer
'400':
description: Validation Error
content:
application/json:
schema:
type: object
properties:
errors:
type: array
minItems: 1
items:
type: object
properties:
code:
type: string
description: Stable lower-snake-case public error code.
detail:
type: string
description: Safe user-facing error detail.
status:
type: string
description: HTTP status code as a string.
source:
type: object
description: Location of the invalid request value.
properties:
pointer:
type: string
description: JSON Pointer to the invalid request value.
parameter:
type: string
description: Name of the invalid query parameter.
header:
type: string
description: Name of the invalid request header.
additionalProperties: false
meta:
type: object
description: Additional error context, including support and provider details when available.
properties:
supportId:
type: string
description: Request/support ID for troubleshooting.
connectionStatus:
type: string
enum:
- login_required
- disconnected
description: External account connection state when the error is repairable by relinking.
provider:
type: object
description: Provider error details, when available.
properties:
name:
type: string
enum:
- plaid
description: Provider that returned the underlying error.
errorCode:
type: string
description: Provider error code, when available.
errorType:
type: string
description: Provider error type, when available.
requestId:
type: string
description: Provider request ID for troubleshooting.
required:
- name
additionalProperties: false
required:
- supportId
additionalProperties: false
required:
- code
- detail
- status
- meta
additionalProperties: false
required:
- errors
additionalProperties: false
examples:
default:
summary: Default
value:
errors:
- code: invalid_value
detail: The information you entered isn't valid. Please check it and try again.
status: '400'
meta:
supportId: req_a1b2c3d4e5f6
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
errors:
type: array
minItems: 1
items:
type: object
properties:
code:
type: string
description: Stable lower-snake-case public error code.
detail:
type: string
description: Safe user-facing error detail.
status:
type: string
description: HTTP status code as a string.
source:
type: object
description: Location of the invalid request value.
properties:
pointer:
type: string
description: JSON Pointer to the invalid request value.
parameter:
type: string
description: Name of the invalid query parameter.
header:
type: string
description: Name of the invalid request header.
additionalProperties: false
meta:
type: object
description: Additional error context, including support and provider details when available.
properties:
supportId:
type: string
description: Request/support ID for troubleshooting.
connectionStatus:
type: string
enum:
- login_required
- disconnected
description: External account connection state when the error is repairable by relinking.
provider:
type: object
description: Provider error details, when available.
properties:
name:
type: string
enum:
- plaid
description: Provider that returned the underlying error.
errorCode:
type: string
description: Provider error code, when available.
errorType:
type: string
description: Provider error type, when available.
requestId:
type: string
description: Provider request ID for troubleshooting.
required:
- name
additionalProperties: false
required:
- supportId
additionalProperties: false
required:
- code
- detail
- status
- meta
additionalProperties: false
required:
- errors
additionalProperties: false
examples:
default:
summary: Default
value:
errors:
- code: unauthenticated
detail: Authentication is required.
status: '401'
meta:
supportId: req_a1b2c3d4e5f6
'403':
description: Forbidden
content:
application/json:
schema:
type: object
properties:
errors:
type: array
minItems: 1
items:
type: object
properties:
code:
type: string
description: Stable lower-snake-case public error code.
detail:
type: string
description: Safe user-facing error detail.
status:
type: string
description: HTTP status code as a string.
source:
type: object
description: Location of the invalid request value.
properties:
pointer:
type: string
description: JSON Pointer to the invalid request value.
parameter:
type: string
description: Name of the invalid query parameter.
header:
type: string
description: Name of the invalid request header.
additionalProperties: false
meta:
type: object
description: Additional error context, including support and provider details when available.
properties:
supportId:
type: string
description: Request/support ID for troubleshooting.
connectionStatus:
type: string
enum:
- login_required
- disconnected
description: External account connection state when the error is repairable by relinking.
provider:
type: object
description: Provider error details, when available.
properties:
name:
type: string
enum:
- plaid
description: Provider that returned the underlying error.
errorCode:
type: string
description: Provider error code, when available.
errorType:
type: string
description: Provider error type, when available.
requestId:
type: string
description: Provider request ID for troubleshooting.
required:
- name
additionalProperties: false
required:
- supportId
additionalProperties: false
required:
- code
- detail
- status
- meta
additionalProperties: false
required:
- errors
additionalProperties: false
examples:
default:
summary: Default
value:
errors:
- code: forbidden
detail: You do not have permission to perform this action.
status: '403'
meta:
supportId: req_a1b2c3d4e5f6
'404':
description: Not Found. Returned when the resource does not exist, or when it exists but is not accessible to your account. The two cases are intentionally indistinguishable, so that resource IDs cannot be enumerated by probing.
content:
application/json:
schema:
type: object
properties:
errors:
type: array
minItems: 1
items:
type: object
properties:
code:
type: string
description: Stable lower-snake-case public error code.
detail:
t
# --- truncated at 32 KB (263 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/natural-ai/refs/heads/main/openapi/natural-ai-payments-api-openapi.yml