OpenAPI Specification
openapi: 3.1.1
info:
title: Natural Agent Keys Transfers 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: Transfers
description: Deposits and withdrawals
paths:
/transfers/deposit:
post:
operationId: transfers.initiateDeposit
summary: Initiate deposit
description: Move funds from a linked bank account into a wallet
tags:
- Transfers
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
attributes:
type: object
properties:
amount:
type: integer
minimum: 100
description: Amount in cents.
currency:
enum:
- USD
type: string
default: USD
description: Three-letter currency code. Currently USD.
externalAccountId:
type: string
pattern: ^eac_[0-9a-f]{32}$
description: External account ID (eac_*).
walletId:
type: string
pattern: ^wal_[0-9a-f]{32}$
description: Target wallet for the deposit. Defaults to your party's default wallet when omitted.
description:
type: string
maxLength: 80
description: Memo for the deposit.
required:
- amount
- externalAccountId
additionalProperties: false
title: DepositCreateAttributes
required:
- attributes
additionalProperties: false
title: DepositCreateData
required:
- data
additionalProperties: false
examples:
default:
summary: Default
value:
data:
attributes:
amount: 50000
currency: USD
externalAccountId: eac_550e8400e29b41d4a716446655440000
description: Wallet top-up
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
type:
type: string
enum:
- transfer
id:
type: string
pattern: ^trf_[0-9a-f]{32}$
attributes:
type: object
properties:
type:
enum:
- deposit
- withdrawal
- internal
type: string
description: Transfer type.
amount:
type: integer
description: Amount in cents.
currency:
type: string
description: Currency code.
status:
enum:
- CREATED
- APPROVAL_DENIED
- PROCESSING
- IN_REVIEW
- COMPLETED
- FAILED
- RETURNED
- CANCELED
type: string
description: Transfer status.
description:
anyOf:
- type: string
- type: 'null'
description: Transfer description.
externalAccountDisplayMask:
anyOf:
- type: string
- type: 'null'
description: Masked external account number.
expectedAvailableAt:
anyOf:
- type: string
- type: 'null'
description: Expected availability time, when known.
failure:
anyOf:
- type: object
properties:
code:
anyOf:
- type: string
- type: 'null'
description: Failure code, when available.
reason:
anyOf:
- type: string
- type: 'null'
description: Failure reason, when available.
required:
- code
- reason
additionalProperties: false
- type: 'null'
description: Failure details when this transfer failed.
return:
anyOf:
- type: object
properties:
code:
anyOf:
- type: string
- type: 'null'
description: Return code, when available.
reason:
anyOf:
- type: string
- type: 'null'
description: Return reason, when available.
returnedAt:
anyOf:
- type: string
- type: 'null'
description: When this transfer returned.
required:
- code
- reason
- returnedAt
additionalProperties: false
- type: 'null'
description: Return details when this transfer was returned.
submittedAt:
anyOf:
- type: string
- type: 'null'
description: When this transfer was submitted.
settledAt:
anyOf:
- type: string
- type: 'null'
description: When this transfer settled.
createdAt:
type: string
description: When this transfer was created.
updatedAt:
anyOf:
- type: string
- type: 'null'
description: When this transfer was last updated.
required:
- type
- amount
- currency
- status
- description
- externalAccountDisplayMask
- expectedAvailableAt
- failure
- return
- submittedAt
- settledAt
- createdAt
- updatedAt
additionalProperties: false
title: TransferAttributes
relationships:
type: object
properties:
party:
type: object
properties:
data:
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.
required:
- data
additionalProperties: false
title: ToOneRelationship
description: Party that owns the transfer.
wallet:
type: object
properties:
data:
type: object
properties:
type:
type: string
enum:
- wallet
id:
type: string
pattern: ^wal_[0-9a-f]{32}$
required:
- type
- id
additionalProperties: false
title: ResourceIdentifier
description: Related resource identifier.
required:
- data
additionalProperties: false
title: ToOneRelationship
description: Wallet for this transfer.
destWallet:
type: object
properties:
data:
anyOf:
- type: object
properties:
type:
type: string
enum:
- wallet
id:
type: string
pattern: ^wal_[0-9a-f]{32}$
required:
- type
- id
additionalProperties: false
title: ResourceIdentifier
description: Related resource identifier.
- type: 'null'
required:
- data
additionalProperties: false
title: NullableToOneRelationship
description: Destination wallet for internal transfers.
externalAccount:
type: object
properties:
data:
anyOf:
- type: object
properties:
type:
type: string
enum:
- externalAccount
id:
type: string
pattern: ^eac_[0-9a-f]{32}$
required:
- type
- id
additionalProperties: false
title: ResourceIdentifier
description: Related resource identifier.
- type: 'null'
required:
- data
additionalProperties: false
title: NullableToOneRelationship
description: External account used for this transfer, when available.
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: Primary transaction for this transfer, when available.
required:
- party
- wallet
- externalAccount
- transaction
additionalProperties: false
title: TransferRelationships
required:
- type
- id
- attributes
- relationships
additionalProperties: false
title: TransferResource
required:
- data
additionalProperties: false
examples:
default:
summary: Default
value:
data:
type: transfer
id: trf_550e8400e29b41d4a716446655440000
attributes:
type: deposit
amount: 50000
currency: USD
status: PROCESSING
description: Wallet top-up
externalAccountDisplayMask: null
expectedAvailableAt: null
failure: null
return: null
submittedAt: '2026-01-04T15:30:00Z'
settledAt: null
createdAt: '2026-01-04T15:30:00Z'
updatedAt: '2026-01-04T15:30:00Z'
relationships:
party:
data:
type: party
id: pty_7c9e6679e29b41d4a716446655440001
wallet:
data:
type: wallet
id: wal_550e8400e29b41d4a716446655440000
externalAccount:
data:
type: externalAccount
id: eac_550e8400e29b41d4a716446655440000
transaction:
data:
type: transaction
id: txn_550e8400e29b41d4a716446655440000
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:
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
# --- truncated at 32 KB (338 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/natural-ai/refs/heads/main/openapi/natural-ai-transfers-api-openapi.yml