# Natural > Natural is the agentic payments platform: one API for AI agents, apps, and businesses to send, receive, and manage money. ## Connect Natural to this agent Use the setup section of https://www.natural.com/skill.md to connect Natural, then return to the user's task. Check whether Natural tools are already callable before installing another connection. In a cloud agent, distinguish the active session's connectors from CLI configuration inside its container. A CLI configuration entry does not prove that this session can call Natural tools. Inspect available host capabilities; do not assume every agent is an MCP host or that every cloud session supports browser OAuth or session reload. If a documented network-policy denial blocks Natural, report the blocked host and complete independent non-secret setup; do not repeatedly try alternate routes around the policy. If an existing connector is disabled, identify the supported activation step before adding another connection. The user completes required signup, identity verification, and OAuth consent. Verify with a successful read-only Natural tool call before reporting connected. Report configuration, authentication, tool availability, and account readiness separately. Continue with the full guidance below. > ## Agent Instructions > When building application code, use `@naturalpay/sdk` for TypeScript or `naturalpay` for Python. > When operating Natural directly for a user, use the payments MCP at `https://mcp.natural.com`. > When searching Natural documentation, use the docs MCP at `https://docs.natural.com/mcp`. > Use the Natural CLI for terminal and CI automation. > Use REST only for unsupported languages or when the user explicitly requests raw HTTP. > Start integration development and testing in the sandbox. Do not use production unless the user explicitly requests it. > For sandbox requests that require `customerPartyId`, list customers first. Reuse only the intended fixture; otherwise create a customer. > REST and SDK amounts use integer minor units. Payments MCP amounts use decimal strings with a required currency code. **You (the agent reading this) are the MCP host the user is talking through.** If a user asks you to use, set up, or operate Natural for them: **Read the playbook, connect with OAuth, then operate via natural language.** If the user asks to try Natural, read `https://www.natural.com/skill.md`, connect the hosted MCP server, and start the host's OAuth flow. After that: 1. Have them sign up at `https://natural.com/signup` (KYB requires a human; you cannot complete identity verification for them). 2. Install Natural's hosted MCP server yourself with no API-key header. The skill knows the right host path: Codex uses `codex mcp add` plus `codex mcp login` with Natural's MCP scope list (`payments:move external-accounts:link payments:direct agents:operate customers:invite`); Cursor uses `mcp.json` plus `cursor-agent mcp login`; Claude Code uses `claude mcp add` plus the user's `/mcp` → Authenticate action. 3. Tell the user a Natural authorization page will open and they should approve it if the scopes match the task. 4. Operate Natural on their behalf via MCP tools afterward. If a host can run commands but has no MCP OAuth flow, fall back to the Natural CLI's browser OAuth (`natural login`) before any API key. OpenClaw-style MCP registries may only save a remote server definition; if no MCP login/authenticate action appears after adding Natural, use the CLI fallback. Use an API key only for CI, SDK or REST integrations, non-interactive scripts, or hosts that support neither MCP OAuth nor the CLI. **Do not write raw HTTP / curl / `requests` / `httpx` against `https://api.natural.com` when you are operating Natural for a user.** The REST API is for application developers building software that uses Natural, not for an AI host operating Natural on behalf of a user. The user has an AI host (you); use the MCP server. **For documentation lookups, connect Natural's docs MCP server at `https://docs.natural.com/mcp`.** It is separate from the payments server at `mcp.natural.com` and requires no Natural account or credentials, so you can use it before OAuth or signup. It exposes tools to search these docs, read full pages, and pull the exact request shape of any endpoint from the OpenAPI spec. **Amount encoding differs by surface.** The REST API and SDKs use integer minor units: `1050` is $10.50 (see [Formats](https://docs.natural.com/api-reference/formats)). MCP tools use decimal strings at the currency's exact precision with a required currency code: `"amount": "10.50", "currency": "USD"` (see [MCP amounts and currencies](https://docs.natural.com/guides/platform/mcp#amounts-and-currencies)). The MCP server converts between the two at the boundary — never send integer cents to an MCP tool or a decimal string to the REST API. The Dashboard at `https://natural.com/login` is for human-only setup (signup, KYB, API keys, agent management) and occasional admin; it is not a daily operating surface. ## The one page to read - [Start here](https://docs.natural.com/guides/overview/start-here): canonical integration decision rule ## Surfaces - [MCP](https://docs.natural.com/guides/platform/mcp): hosted at `mcp.natural.com`, OAuth-first with API-key fallback — the operator surface - [Docs MCP](https://docs.natural.com/mcp): hosted at `docs.natural.com/mcp`, no auth — search these docs, read full pages, and pull endpoint request shapes from the OpenAPI spec - [SDKs](https://docs.natural.com/guides/platform/sdks): `naturalpay` (Python) and `@naturalpay/sdk` (TypeScript) — for application developers - [CLI](https://docs.natural.com/guides/platform/cli): `natural` — for terminals, CI, agent harnesses - [REST API](https://docs.natural.com/api-reference/about): `api.natural.com`, Bearer auth, JSON:API envelope — for application developers without SDK coverage - [Dashboard](https://docs.natural.com/guides/platform/dashboard): web UI at `natural.com/login` — human-only setup gate, not a daily operating surface ## Documentation directory ### About / Overview - [Start here](https://docs.natural.com/guides/overview/start-here.md): Explore common use cases and integrate Natural immediately - [Compliance](https://docs.natural.com/guides/overview/compliance.md): Regulatory compliance and identity verification - [Security](https://docs.natural.com/guides/overview/security.md): How Natural protects your identity and banking details, and controls who can move money ### About / Common use cases - [Store funds](https://docs.natural.com/guides/flows/wallets-and-balances.md): Hold money on Natural and let your agent manage it - [Send payments](https://docs.natural.com/guides/flows/send-money.md): Your agent pays anyone by email, phone, or handle - [Request money](https://docs.natural.com/guides/flows/collect-money.md): Your agent requests from anyone by email, phone, or handle - [Accept payments](https://docs.natural.com/guides/flows/accept-payments.md): Turn your agent into a merchant - [Payments over Voice](https://docs.natural.com/guides/flows/accept-voice.md): Turn a phone call into a PCI-compliant payment - [Issue cards](https://docs.natural.com/guides/flows/issue-cards.md): Give your agents cards to pay merchants online ### About / Common use cases / Build a platform - [Overview](https://docs.natural.com/guides/flows/build-platform.md): Build a platform where your agent uses all of Natural's products on behalf of your customers with Connect - [Embedded finance](https://docs.natural.com/guides/flows/platform-embedded-finance.md): Request, collect, and pay funds inside each customer's own wallet, with balances held in the customer's name - [AP/AR](https://docs.natural.com/guides/flows/platform-ap-ar.md): Run a customer's payables and receivables end to end: collect what's owed, pay the bills, and reconcile both sides - [Agentic commerce](https://docs.natural.com/guides/flows/platform-agentic-commerce.md): An agent that transacts in the open market on your customer's behalf, accepting payments and paying counterparties at machine speed - [Treasury management](https://docs.natural.com/guides/flows/platform-treasury.md): Put a customer's idle cash to work: link their accounts, stage funds in a Natural wallet, and move cash under the controls they delegated ### About / Products - [Wallet](https://docs.natural.com/guides/products/wallet.md): Store funds in FDIC-insured accounts to hold, send, and receive funds, all from an API - [Vault](https://docs.natural.com/guides/products/vault.md): Receive expanded FDIC coverage with a special protected wallet for your financial reserves - [Pay](https://docs.natural.com/guides/products/pay.md): Pay anyone by email, phone, handle, party ID, or agent ID with one API call - [Request](https://docs.natural.com/guides/products/request.md): Request a payment from an agent, email, or phone number with a single API call - [Transfer](https://docs.natural.com/guides/products/transfer.md): Move money between your wallets and your linked bank accounts, with automated treasury management for your agents - [Connect](https://docs.natural.com/guides/products/connect.md): Build a platform that enables money movement for your customers across all of Natural's products - [Voice](https://docs.natural.com/guides/products/voice.md): Collect card payments over the phone - [Cards](https://docs.natural.com/guides/products/cards.md): Issue debit and charge cards for your agents the moment they're connected - [Accept](https://docs.natural.com/guides/products/accept.md): Accept card payments by checkout link or voice ### About / Guides / Agents - [Create an agent](https://docs.natural.com/guides/agents/create-agent.md): Create an agent and get back its agent ID - [Manage your agents](https://docs.natural.com/guides/agents/manage-agents.md): List and edit your agents - [Claim a handle](https://docs.natural.com/guides/agents/handles.md): Claim a @handle to give you and your agents an identity ### About / Guides / Wallets - [Create and manage wallets](https://docs.natural.com/guides/wallets/wallets.md): Create and manage your wallets - [Use the Vault](https://docs.natural.com/guides/wallets/vault.md): A reserve wallet agents can fund but never spend from ### About / Guides / Controls - [Set limits](https://docs.natural.com/guides/controls/limits.md): Limit how much each agent can move per transaction, per day, and per month - [Give an agent wallet access](https://docs.natural.com/guides/controls/wallet-access.md): Give agents access to wallets to move money - [Approve or deny a held payment](https://docs.natural.com/guides/controls/approvals.md): Approve or deny a payment held for review ### About / Guides / Transfers - [Transfer between wallets](https://docs.natural.com/guides/transfers/transfer-between-wallets.md): Move money instantly between two wallets - [Deposit and withdraw](https://docs.natural.com/guides/transfers/deposit-and-withdraw.md): Move money between a linked bank account and your wallet ### About / Guides / Payments - [Send a payment](https://docs.natural.com/guides/payments/send-payment.md): Pay anyone by email, phone, party ID, agent ID, or @handle - [Request a payment](https://docs.natural.com/guides/payments/request-payment.md): Collect money from anyone with a payment link that Natural delivers for you - [Track a payment](https://docs.natural.com/guides/payments/track-payment.md): Follow a payment through its lifecycle - [Fulfill or decline a payment request](https://docs.natural.com/guides/payments/fulfill-or-decline-request.md): Pay a request addressed to you from a wallet or bank account ### About / Guides / Connect - [Invite a customer](https://docs.natural.com/guides/connect/invite-customer.md): Invite a specific customer or share an invitation link to connect your agents - [Move money for a customer](https://docs.natural.com/guides/connect/move-money-for-customer.md): Pay and request on a customer's behalf - [Manage customer access](https://docs.natural.com/guides/connect/manage-access.md): Manage agents across your connected customers ### About / Guides / Webhooks - [Receive events](https://docs.natural.com/guides/webhooks/receive-events.md): Register a webhook, verify each delivery, and handle retries ### About / Guides / Accept - [Create a payment intent and get paid by link](https://docs.natural.com/guides/accept/pay-by-link.md): Create a payment intent and share its checkout link - [Refund a card payment](https://docs.natural.com/guides/accept/refund-a-card-payment.md): Return part or all of a card payment to the card that paid - [Accept in Sandbox](https://docs.natural.com/guides/accept/test-in-sandbox.md): Test card payments and settlement without moving real money ### About / Guides / Voice - [Take a payment over voice](https://docs.natural.com/guides/voice/take-a-payment.md): Collect a card payment during a phone call - [Read the call log](https://docs.natural.com/guides/voice/call-log.md): Review voice sessions and redacted transcripts ### API Reference / Overview - [About the Natural API](https://docs.natural.com/api-reference/about.md): Understanding the structure of Natural API requests and responses ### API Reference / Overview / Our interfaces - [MCP](https://docs.natural.com/guides/platform/mcp.md): Connect AI hosts to Natural's hosted MCP server - [SDKs](https://docs.natural.com/guides/platform/sdks.md): Client libraries for building agents with Natural - [CLI](https://docs.natural.com/guides/platform/cli.md): Test, provision, and debug the Natural API from your terminal while you build an agent - [Dashboard](https://docs.natural.com/guides/platform/dashboard.md): Monitor and control your agents, wallets, and payments ### API Reference / Overview / Our technology - [Authentication](https://docs.natural.com/api-reference/authentication.md): API keys, agent keys, OAuth, and Bearer authentication - [IDs](https://docs.natural.com/api-reference/IDs.md): Prefixed identifiers (`pty_`, `agt_`, `wal_`, `eac_`, `pay_`, `prq_`, `trf_`, `txn_`, `pmi_`, `cpy_`, `rfd_`, `vos_`, `cbk_`, `evf_`, `pcd_`, `cit_`, `csn_`, `amd_`, `apm_`, `apu_`, `epty_`, `epa_`, `ach_`, `wire_`, `rt_`, `mdt_`, `cpc_`) - [Formats](https://docs.natural.com/api-reference/formats.md): Data formats and units used across the API - [Idempotency](https://docs.natural.com/api-reference/idempotency.md): Ensuring safety when retrying a mutation - [Pagination](https://docs.natural.com/api-reference/pagination.md): Cursor-based pagination for list endpoints - [Rate limits](https://docs.natural.com/api-reference/rate-limits.md): API request rate limiting - [Backwards compatibility](https://docs.natural.com/api-reference/backwards-compatibility.md): What Natural will and will not change in the API - [Reliability](https://docs.natural.com/guides/platform/reliability.md): How Natural stays available and behaves predictably under failure ### API Reference / Overview / Our technology / Sandbox - [Sandbox](https://docs.natural.com/api-reference/sandbox/overview.md): Experience Natural without moving real money - [Payment fixtures](https://docs.natural.com/api-reference/sandbox/fixtures.md): Reserved test identifiers and synthetic counterparties for your sandbox organization - [Card fixtures](https://docs.natural.com/api-reference/sandbox/card-fixtures.md): Test successful payments, declines, plans, settlement, cancels, and refunds in sandbox - [Sandbox from MCP, CLI, and SDKs](https://docs.natural.com/api-reference/sandbox/surfaces.md): Connect to the Natural Sandbox ### API Reference / Agents - [Overview](https://docs.natural.com/guides/concepts/agents.md): Autonomous actors that can move money ### API Reference / Customers - [Overview](https://docs.natural.com/guides/concepts/customers.md): Customers are parties who have authorized your agents to act for them ### API Reference / Customers / Simulations - [Sandbox: Invite a test customer](https://docs.natural.com/api-reference/simulations/create-test-customer.md): Create a synthetic Connect customer and pending invitations in Sandbox. - [Sandbox: Fund a Connect customer](https://docs.natural.com/api-reference/simulations/fund-test-customer.md): Add funds to a Connect customer's Sandbox balance. - [Sandbox: Accept a Connect invitation](https://docs.natural.com/api-reference/simulations/accept-customer-invitation.md): Accept a pending Connect invitation as a test customer in Sandbox. - [Sandbox: Decline a Connect invitation](https://docs.natural.com/api-reference/simulations/decline-customer-invitation.md): Decline a pending Connect invitation as a test customer in Sandbox. - [Sandbox: Revoke Connect access](https://docs.natural.com/api-reference/simulations/revoke-agent-connection.md): End an agent's access to a Connect customer in Sandbox. - [Sandbox: Disconnect a Connect customer](https://docs.natural.com/api-reference/simulations/disconnect-customer.md): End a test customer's full Connect relationship in Sandbox. ### API Reference / Payments - [Overview](https://docs.natural.com/guides/concepts/payments.md): Send and receive money via direct payments or payment claims ### API Reference / Payments / Simulations - [Sandbox: Complete a payment claim](https://docs.natural.com/api-reference/simulations/complete-payment-claim.md): Complete a payment claim in Sandbox. ### API Reference / Payments / Direct: External parties - [Overview](https://docs.natural.com/guides/concepts/external-parties.md): Third parties you transact with over Direct, and their banking details ### API Reference / Payments / Direct: ACH - [Overview](https://docs.natural.com/guides/concepts/ach.md): Make ACH payments to external party accounts ### API Reference / Payments / Direct: Realtime - [Overview](https://docs.natural.com/guides/concepts/realtime.md): Send realtime payments to external party accounts ### API Reference / Payments / Direct: Realtime / Simulations - [Sandbox: Settle a realtime payment](https://docs.natural.com/api-reference/simulations/settle-realtime-payment.md): Drive a Sandbox realtime payment to settlement. - [Sandbox: Fail a realtime payment](https://docs.natural.com/api-reference/simulations/fail-realtime-payment.md): Drive a Sandbox realtime payment to a terminal network rejection. ### API Reference / Payments / Direct: Wire - [Overview](https://docs.natural.com/guides/concepts/wire.md): Send domestic USD wires to external party accounts ### API Reference / Payments / Direct: Wire / Simulations - [Sandbox: Complete a wire](https://docs.natural.com/api-reference/simulations/settle-wire.md): Drive a sandbox wire to completion. - [Sandbox: Reject a wire](https://docs.natural.com/api-reference/simulations/fail-wire.md): Drive a sandbox wire to a bank rejection. ### API Reference / Transactions - [Overview](https://docs.natural.com/guides/concepts/transactions.md): The single ledger of every money movement on your account ### API Reference / Transfers - [Overview](https://docs.natural.com/guides/concepts/transfers.md): Move money between your wallets and your linked bank accounts ### API Reference / Payment Requests - [Overview](https://docs.natural.com/guides/concepts/payment-requests.md): Request, accept, and reconcile payment from another party ### API Reference / Payment Requests / Simulations - [Sandbox: Fulfill a payment request](https://docs.natural.com/api-reference/simulations/fulfill-payment-request.md): Pay a Sandbox payment request from the test payer's funded wallet. - [Sandbox: Decline a payment request](https://docs.natural.com/api-reference/simulations/decline-payment-request.md): Decline a payment request as a test payer in Sandbox. ### API Reference / Payment Intents - [Overview](https://docs.natural.com/guides/concepts/payment-intents.md): Collect a card payment by checkout link or voice ### API Reference / Plans - [Overview](https://docs.natural.com/guides/concepts/plans.md): Charge a payer's card on a schedule they agreed to ### API Reference / Card Payments - [Overview](https://docs.natural.com/guides/concepts/card-payments.md): Inspect card payment attempts and refunds ### API Reference / Card Payments / Simulations - [Sandbox: Settle a card payment](https://docs.natural.com/api-reference/simulations/settle-card-payment.md): Settle a successful sandbox card payment into the receiving wallet. ### API Reference / Voice Sessions - [Overview](https://docs.natural.com/guides/concepts/voice-sessions.md): Collect a payment intent over a phone call with a single SIP transfer ### API Reference / Refunds - [Overview](https://docs.natural.com/guides/concepts/refunds.md): Return part or all of a card payment to the payer ### API Reference / Chargebacks - [Overview](https://docs.natural.com/guides/concepts/chargebacks.md): Review and respond to card payment chargebacks ### API Reference / Approvals - [Overview](https://docs.natural.com/guides/concepts/approvals.md): Payments and transfers held for review by a spending limit ### API Reference / Limits - [Overview](https://docs.natural.com/guides/concepts/limits.md): Limits on how much money can move without extra approval ### API Reference / Parties - [Overview](https://docs.natural.com/guides/concepts/parties.md): The real-world identity behind your wallets and agents ### API Reference / Party Invitations - [Overview](https://docs.natural.com/guides/concepts/party-invitations.md): Invite teammates to join your party ### API Reference / Wallets - [Overview](https://docs.natural.com/guides/concepts/wallets.md): Where a party holds and moves its funds ### API Reference / Wallet Access - [Overview](https://docs.natural.com/guides/concepts/wallet-access.md): Which of your wallets each agent can move money from ### API Reference / External Accounts - [Overview](https://docs.natural.com/guides/concepts/external-accounts.md): Bank accounts linked to a party for deposits and withdrawals ### API Reference / External Accounts / Simulations - [Sandbox: Link a test bank account](https://docs.natural.com/api-reference/simulations/link-test-bank-account.md): Link a test bank account to your own party in Sandbox. ### API Reference / Cards - [Overview](https://docs.natural.com/guides/concepts/cards.md): The cards Natural supports, and how people and agents use them ### API Reference / Cards / Saved cards - [Saved cards](https://docs.natural.com/guides/concepts/saved-cards.md): External cards users save on the dashboard ### API Reference / Agent checkout - [Overview](https://docs.natural.com/guides/concepts/agent-checkout.md): Let agents pay with a card without handling the real card number ### API Reference / Agent checkout / Browser tokens - [Overview](https://docs.natural.com/guides/concepts/browser-tokens.md): Let agents check out through a browser proxy without seeing the real card number ### API Reference / Agent checkout / Agent tokens - [Overview](https://docs.natural.com/guides/concepts/agent-tokens.md): Let agents spend from an approved budget without seeing the real card number ### API Reference / API Keys - [Overview](https://docs.natural.com/guides/concepts/api-keys.md): Your party's server-side credential ### API Reference / Agent Keys - [Overview](https://docs.natural.com/guides/concepts/agent-keys.md): Credentials bound to a single agent ### API Reference / Webhooks - [Overview](https://docs.natural.com/guides/concepts/webhooks.md): Get notified when things happen on your account ### API Reference / Events - [Overview](https://docs.natural.com/guides/concepts/events.md): The record of what happened on your account - [Event types](https://docs.natural.com/api-reference/event-catalog.md): Complete reference of all webhook event types and their payloads ### API Reference / Errors - [Error handling](https://docs.natural.com/api-reference/errors/error-handling.md): Standard error format and recovery patterns ### API Reference / Errors / Resource errors - [Agents](https://docs.natural.com/api-reference/errors/agents.md): Public error codes for Agents API endpoints - [Customers](https://docs.natural.com/api-reference/errors/customers.md): Public error codes for Customers API endpoints - [Payments](https://docs.natural.com/api-reference/errors/payments.md): Public error codes for Payments API endpoints - [Transactions](https://docs.natural.com/api-reference/errors/transactions.md): Public error codes for Transactions API endpoints - [Transfers](https://docs.natural.com/api-reference/errors/transfers.md): Public error codes for Transfers API endpoints - [Payment Requests](https://docs.natural.com/api-reference/errors/payment-requests.md): Public error codes for Payment Requests API endpoints - [Payment Intents](https://docs.natural.com/api-reference/errors/payment-intents.md): Public error codes for Payment Intents API endpoints - [Card Payments](https://docs.natural.com/api-reference/errors/card-payments.md): Public error codes for Card Payments API endpoints - [Voice Sessions](https://docs.natural.com/api-reference/errors/voice-sessions.md): Public error codes for Voice Sessions API endpoints - [Refunds](https://docs.natural.com/api-reference/errors/refunds.md): Public error codes for Refunds API endpoints - [Chargebacks](https://docs.natural.com/api-reference/errors/chargebacks.md): Public error codes for Chargebacks API endpoints - [Approvals](https://docs.natural.com/api-reference/errors/approvals.md): Public error codes for Approvals API endpoints - [Parties](https://docs.natural.com/api-reference/errors/parties.md): Public error codes for Parties API endpoints - [Party Invitations](https://docs.natural.com/api-reference/errors/party-invitations.md): Public error codes for Party Invitations API endpoints - [Wallets](https://docs.natural.com/api-reference/errors/wallets.md): Public error codes for Wallets API endpoints - [External Accounts](https://docs.natural.com/api-reference/errors/external-accounts.md): Public error codes for External Accounts API endpoints - [External Parties](https://docs.natural.com/api-reference/errors/external-parties.md): Public error codes for External Parties API endpoints - [External Party Accounts](https://docs.natural.com/api-reference/errors/external-party-accounts.md): Public error codes for External Party Accounts API endpoints - [ACH](https://docs.natural.com/api-reference/errors/ach.md): Public error codes for ACH API endpoints - [Realtime](https://docs.natural.com/api-reference/errors/realtime.md): Public error codes for Realtime API endpoints - [Wire](https://docs.natural.com/api-reference/errors/wire.md): Public error codes for Wire API endpoints - [API keys](https://docs.natural.com/api-reference/errors/api-keys.md): Public error codes for API keys API endpoints - [Agent keys](https://docs.natural.com/api-reference/errors/agent-keys.md): Public error codes for Agent keys API endpoints - [Card sessions](https://docs.natural.com/api-reference/errors/card-sessions.md): Public error codes for Card sessions API endpoints - [Webhooks](https://docs.natural.com/api-reference/errors/webhooks.md): Public error codes for Webhooks API endpoints - [Events](https://docs.natural.com/api-reference/errors/events.md): Public error codes for Events API endpoints ### API endpoint reference - [OpenAPI specification](https://docs.natural.com/api-reference/openapi.json): Canonical endpoint shapes. Query the [docs MCP](https://docs.natural.com/mcp) to find and read them. ## Full text - [llms-full.txt](https://docs.natural.com/llms-full.txt): every documentation page concatenated, for full-context retrieval