# Natural

> Natural is the agentic payments platform — one API for AI agents, apps, and businesses to send, receive, and manage money.

**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://natural.co/skill.md`, connect the hosted MCP server, and start the host's OAuth flow. After that:

1. Have them sign up at `https://natural.co/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 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.co` 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.

The Dashboard at `https://natural.co/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.co/guides/overview/start-here): canonical integration decision rule

## Surfaces

- [MCP](https://docs.natural.co/guides/platform/mcp): hosted at `mcp.natural.co`, OAuth-first with API-key fallback — the operator surface
- [SDKs](https://docs.natural.co/guides/platform/sdks): `naturalpay` (Python) and `@naturalpay/sdk` (TypeScript) — for application developers
- [CLI](https://docs.natural.co/guides/platform/cli): `natural` — for terminals, CI, agent harnesses
- [REST API](https://docs.natural.co/guides/platform/apis): `api.natural.co`, Bearer auth, JSON:API envelope — for application developers without SDK coverage
- [Dashboard](https://docs.natural.co/guides/platform/dashboard): web UI at `natural.co/login` — human-only setup gate, not a daily operating surface

## Common tasks

- [Create a payment](https://docs.natural.co/guides/create-payment): end-to-end send with agent and customer context
- [Request a payment](https://docs.natural.co/guides/request-payment): collect via a hosted payment link
- [Webhook integration](https://docs.natural.co/guides/webhooks-integration): Standard Webhooks signatures and event handling

## API reference

- [Authentication](https://docs.natural.co/api-reference/authentication): API keys, scopes, security
- [Request/response shape](https://docs.natural.co/api-reference/about): JSON:API conventions
- [IDs](https://docs.natural.co/api-reference/IDs): prefixed identifiers (`pty_`, `agt_`, `pay_`, `txn_`, `prq_`, `eac_`)
- [Idempotency](https://docs.natural.co/api-reference/idempotency): retry safety for mutating operations
- [Error handling](https://docs.natural.co/api-reference/errors/error-handling): standard error shape
- [OpenAPI spec](https://docs.natural.co/api-reference/openapi.json): machine-readable spec for codegen

## Concepts (read on demand)

- [Parties](https://docs.natural.co/guides/concepts/parties): identity unit — business or individual
- [Users](https://docs.natural.co/guides/concepts/users): authenticated people and party memberships
- [Agents](https://docs.natural.co/guides/concepts/agents): autonomous entities that execute payments
- [Wallets](https://docs.natural.co/guides/concepts/wallets): USD-backed balances per party
- [Payments](https://docs.natural.co/guides/concepts/payments): money movement primitives

## Full text

- [llms-full.txt](https://docs.natural.co/llms-full.txt): every documentation page concatenated, for full-context retrieval