Integration Paths

There are multiple ways to build on SohoPay, depending on which side of the payment rail you operate. This guide helps you identify your track and lists the exact guides to follow, in order. If you haven’t completed the Quickstart yet, we recommend starting there to understand the core x402 payment flow.

---

​

The four integration tracks

---

​

Compare the paths

---

​

Which path should I choose?

Answer the following questions to find your track:

• Do you use Cursor IDE, Claude Desktop, or Windsurf and want your AI to pay for external resources?
  👉 Choose Track 1: MCP Agent. Run npx @sohopay/mcp-server login and start spending in minutes.
• Do you sell APIs, data, compute, or digital subscriptions that AI agents should pay for?
  👉 Choose Track 2: Merchant Integration. Accept x402 payments and receive USDC on Base.
• Are you building an autonomous backend agent system in Python or TypeScript?
  👉 Choose Track 3: Programmatic Agent Platform. Provision operational agents via API and implement EIP-712 signing.
• Are you building a private sandbox or platform where your agents pay your own internal services?
  👉 Choose Track 4: Full End-to-End. Wire both sides together using the payment flow.
• Just evaluating protocol standards?
  👉 Explore x402 Protocol Specs and the Trust Model.

---

​

Step-by-step roadmap for each track

​

Track 1: AI Agent via MCP (~5 minutes)

Equip your AI assistants with instant credit lines:

1. Quickstart (Option A) — Pair your local terminal with your account via CLI and configure your IDE.
2. Borrower Portal — View your real-time available credit, pause/resume active agents, and test wallet repayment.
3. Operator Liability — Review credit facility terms and operator responsibilities.

​

Track 2: Merchant Integration (~3–5 days)

Expose orders and accept instant on-chain settlement:

1. Merchant Integration Walkthrough — End-to-end payment lifecycle for merchants.
2. Merchant Onboarding & KYB — Account setup, payout wallet verification, and KYB.
3. Allowlist Management — Manage which agents are permitted to purchase from your catalog.
4. Settlements & Payouts — Automated USDC payouts to your registered Base wallet.
5. Webhooks — Consume payment.settled events in real-time.

​

Track 3: Programmatic Agent Platform (~2–3 days)

Provision agents programmatically and manage signing infrastructure:

1. Agent Setup Guide — Create operational agents with credit_limit and daily_limit.
2. Key Management — Implement 2-of-3 MPC key shares and EIP-712 typed signing.
3. Vault Funding — Deposit USDC collateral into your vault to establish your borrowing capacity.
4. Rate Limits — Configure per-agent spend policies and hourly volume caps.

​

Track 4: Full End-to-End Platform (~5–7 days)

Connect both sides into a unified marketplace:

1. Complete Track 2 (Merchant Integration) to onboard your services and initialize allowlists.
2. Complete Track 3 (Agent Setup) to provision agents and approve allowlists.
3. Payment Flow — Test the complete order → sign → settle loop with 10-minute order TTLs.
4. Error Handling — Implement robust retry logic, decline handling, and timeout safeguards.
5. Testing Guide — Validate failure scenarios and rate limits in the sandbox.

---

​

Next steps