Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.natural.co/llms.txt

Use this file to discover all available pages before exploring further.

Send money to an agent, email, phone number, or Natural party ID. For new parties, Natural creates a payment link, delivers the link by email or SMS, and onboards the new party.
Every call is shown five ways — MCP · Python · TypeScript · CLI · cURL. The MCP tab is the natural-language prompt you’d give an AI agent.

​
1. Get your API key

Sign up at natural.co/signup (Google OAuth, email/password, or phone) and complete identity verification, KYC for individuals, KYB for businesses. See compliance for details. Then create a developer API key in the dashboard. It’s shown once, store it in a secret manager and never in version control. 
export NATURAL_API_KEY=sk_ntl_prod_abc123...
Connect to MCP, CLI, or SDK: 
claude mcp add --transport http natural https://mcp.natural.co \
  --header "Authorization: Bearer $NATURAL_API_KEY"
That registers the hosted MCP server with Claude Code.
Point any MCP client at the same endpoint with a JSON config:
{
  "mcpServers": {
    "natural": {
      "type": "http",
      "url": "https://mcp.natural.co",
      "headers": { "Authorization": "Bearer sk_ntl_prod_..." }
    }
  }
}

​
2. Create an agent

Agents execute transactions. Create one in the Agents tab of the dashboard, or: 
Create an agent called "Carrier Payment Agent" for paying delivery carriers.
The response includes the agent’s id (agt_*), store it to associate your agent for future requests.

​
3. Connect a bank account and fund your wallet

Fund your wallet from a linked bank account so your agent can transact autonomously.

​
Connect a bank account

Link a bank account from the Wallet tab of your dashboard — Natural connects it securely through Plaid. Once linked, list your external accounts to get the eac_* ID to deposit from: 
List my linked bank accounts.
Each linked account has an id (eac_*) — you’ll pass it to the deposit call below.

​
Fund your wallet

Pull funds from the linked account into your wallet: 
Deposit $50,000 into my wallet from my linked bank account.
Confirm the funds landed before paying. Each wallet’s balance.available is the spendable balance after pending holds: 
What's my wallet's available balance?

​
4. Send the payment

Using my Carrier Payment Agent, pay terri@contractor.com $5,000 for Q4 development work.
The response includes the payment’s id (pay_*) and an initial status.

​
5. Track the payment

Check the payment’s status with the id from step 4: 
Check the status of that payment.
Statuses move CREATED → PROCESSING → COMPLETED. A payment can also sit at PENDING_CLAIM (awaiting the recipient) or IN_REVIEW (compliance hold), or end at FAILED, CANCELLED, or APPROVAL_DENIED. List and filter with GET /transactions, or subscribe to webhooks instead of polling.

​
Paying on behalf of a customer

To pay from a customer’s wallet, the customer first delegates payment authority to your agent. Invite them: 
Invite bruce@propertymanagement.com to my Carrier Payment Agent.
The customer gets an email, completes onboarding, and approves the agent-customer relationship. After that, add their party ID as customerPartyId when sending — the payment then draws from their wallet instead of yours. Find a customer’s customerPartyId via GET /customers — each customer resource’s id is the party ID.