eac_*) into a wallet (wal_*) as a transfer (trf_*), or push it back out. For the transfer lifecycle, read the Transfer object.
Natural handles the payment rails, so you can use whichever fits. Any connected agent can move money with an API call, and every transfer is observable and fully auditable.
Before you start, connect Natural to your agent or create an API key. See Start here. Setup takes a couple of minutes; the MCP path needs no API key.
If an MCP host is operating Natural for you, use the MCP example. The linked API reference has
per-language samples and a playground.
Link a bank account in the dashboard first. Natural returns an
eac_* id you pass on every
deposit and withdrawal. The account must be verified and its connection active; otherwise the call
returns 409 externalAccount.notVerified or externalAccount.connectionLoginRequired.Amounts are integer US cents:
50000 is $500.00.Deposit into a wallet
Pull money from the bank into a wallet withPOST /transfers/deposit. Funds land in your default wallet unless you name another. The minimum deposit is 100 ($1.00), and deposits are capped per day by your tier (deposit.tierDailyPullLimitExceeded).
When an agent (
agt_*) creates, cancels, fulfills, or declines a payment, payment request,
transfer, payment intent, refund, or voice session, it authenticates with its own credential (an
agent key or an agent-scoped OAuth grant) and names
the run with the X-Instance-ID header. Without it the call returns 400 missingInstanceId.
Reads don’t need it.trf_*) in PROCESSING:
CREATED to PROCESSING to COMPLETED. It can pause at IN_REVIEW during an approval hold. It ends at FAILED, RETURNED, CANCELED, or APPROVAL_DENIED.
Withdraw to a bank account
Push money from a wallet to the bank withPOST /transfers/withdraw. Natural pulls from your default wallet unless you name another, and the wallet needs enough available balance to cover it (otherwise 409 wallet.insufficientFunds). Withdrawals go out over ACH by default; pass method: "instant" for a realtime withdrawal where your account has access, otherwise the call returns 403 instantWithdrawal.notEnabled.
trf_*) in PROCESSING:
Confirm the balance
Deposits and withdrawals settle asynchronously, so the balance change is not immediate. Read the transfer withGET /transfers/{transferId}: status moves PROCESSING to COMPLETED, and expectedAvailableAt tells you when the funds are usable. Then read the wallet to confirm a deposit landed before you spend against it, or that a withdrawal left. See Create and manage wallets for how balance.available differs from balance.total.
data.object.relationships.initiatorAgent.data.id identifies the agent that initiated the deposit or withdrawal, including when it acts for a connected customer. It stays the same through approval, completion, failure, cancellation, and return. The relationship’s data is null for non-agent activity, externally observed deposits, or historical transfers without reliable agent attribution.
Use the top-level sourcePartyId to identify the party the transfer belongs to. Connected and own deliveries carry the same attribution. Previously stored events retain their original payload on redelivery and may omit the initiatorAgent relationship.