Skip to main content
SouthPay lets an AI agent operate a merchant store: create payments, watch them settle, read balances and rates, and, once a human has configured the controls, issue refunds and disburse payouts. Agents authenticate with an agent credential (spa_live_… / spa_test_…), which is a distinct credential type from an API key or an OAuth token. There are two ways in, and they reach the same endpoints:
  • The hosted MCP server at https://mcp.southpay.io/mcp, exposing 19 tools to any Model Context Protocol client.
  • The agentic REST API at /api/v2/agentic/*, with Authorization: Bearer spa_….
The MCP server is a thin proxy over the REST API with no logic of its own, so anything gated in one is gated identically in the other. Session mandates and x402 settlements are REST-only.

​
What works out of the box

Money movement fails closed. On a store with no extra configuration: Spend limits are configured by the merchant in the dashboard. The rest need an authorization provider, which SouthPay support enables per store. Agent authorization covers exactly what unblocks what.

​
How the pieces fit

  • Agent credentials. Bearer tokens carrying up to eight scopes and an optional expiry, created by the merchant in the dashboard or minted through the OAuth exchange.
  • Authorization. Three controls that compose: credential scopes, per-asset spend limits with a daily counter, and mandates verified by an authorization provider.
  • MCP server. Connection, sessions, browser login, and the full tool reference.
  • x402 and session mandates. Capped envelopes for pay-per-call machine-to-machine commerce. Ledger-only unless on-chain dispatch is enabled.

​
Isolation

An agent sees only its own records. Every agentic query is filtered by the calling credential, so payments, payouts, refunds and settlements created by one credential are invisible to another on the same store. An agent also cannot manage credentials, neither its own nor any other. Credentials are mode-locked by their prefix. A spa_test_ credential sees only test-mode data, where the single usable asset is SETH on Ethereum Sepolia. A spa_live_ credential sees only live data. There is no mode header on the agentic API.

​
Rate limits

Agentic endpoints allow 600 requests per minute per credential in live mode, with a burst of 100, returning 429 with code rate_limited when exceeded. Every 429 carries a Retry-After header in seconds. The budget is shared across every agentic path, so payments, payouts and refunds all draw from it. GET /api/v2/agentic/market_data is the exception: it is deliberately unauthenticated and limited to 30 requests per minute per IP. See Rate limits for every throttled path on the API.

​
Get started

Quickstart

Create a credential, connect a client, and take an agent-driven payment.

MCP server

Connection, browser login, and all 19 tools with their parameters.

Authorization

What is blocked by default and what unblocks it.

API reference

Every /api/v2/agentic/* endpoint with request and response shapes.
Last modified on August 21, 2026