Environment Setup

This guide covers everything your environment needs before you integrate with SohoPay: which base URLs to call, how to configure MCP clients (Cursor, Claude Desktop, Windsurf), how to reach Base networks, and how to store API keys safely.

Environments at a glance

SohoPay maintains two isolated environments. Keys, agents, credit facilities, orders, and webhooks never cross between them.

Service / Property	Staging (Sandbox)	Production (Mainnet)
Hosted MCP Server (Remote)	`https://staging.mcp.sohopay.xyz/mcp`	`https://mcp.sohopay.xyz/mcp`
REST API Gateway	`https://staging.api.sohopay.xyz/api/v1`	`https://api.sohopay.xyz/api/v1`
MCP Gateway URL (CLI)	`https://staging.api.sohopay.xyz/api/v1`	`https://api.sohopay.xyz/api/v1`
Borrower Portal	staging.borrower.sohopay.xyz	borrower.sohopay.xyz
Merchant Dashboard	staging.sohopay.xyz	app.sohopay.xyz
Blockchain Network	Base Sepolia (testnet)	Base (mainnet)
Chain ID	`84532`	`8453`
USDC Contract Address	`0x036CbD53842c5426634e7929541eC2318f3dCF7e`	`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
API Key Prefix	`sk_test_...`	`sk_live_...`
KYB Verification	Skipped	Required for merchants

SohoPay production access is currently rolling out to beta integrators. For mainnet production onboarding slots, contact your account representative or reach out in the beta Slack (see Support).

Configure your environment

Select the tab that matches your integration model:

AI Agent / MCP Integration
REST API & Backend Services

If you are operating AI assistants (Cursor IDE, Claude Desktop, Windsurf, or custom agent frameworks) using the Model Context Protocol:

1. Terminal Pairing

Run the login CLI command to pair your local terminal with your account:

# Staging / Sandbox
npx @sohopay/mcp-server login --gateway https://staging.api.sohopay.xyz/api/v1

# Production / Mainnet
npx @sohopay/mcp-server login --gateway https://api.sohopay.xyz/api/v1

2. Client Configuration

You can connect directly via SohoPay’s hosted remote MCP server (recommended, zero local setup) or configure a local stdio client:

{
  "mcpServers": {
    "sohopay-staging": {
      "serverUrl": "https://staging.mcp.sohopay.xyz/mcp"
    }
  }
}

{
  "mcpServers": {
    "sohopay-staging": {
      "url": "https://staging.mcp.sohopay.xyz/mcp"
    }
  }
}

{
  "mcpServers": {
    "sohopay-staging": {
      "serverUrl": "https://staging.mcp.sohopay.xyz/mcp"
    }
  }
}

{
  "mcpServers": {
    "sohopay": {
      "command": "npx",
      "args": ["-y", "@sohopay/mcp-server@latest"],
      "env": {
        "SOHOPAY_GATEWAY_URL": "https://staging.api.sohopay.xyz/api/v1"
      }
    }
  }
}

If you are integrating backend services, merchant checkouts, or custom agents via REST:

Staging / Sandbox

Point your client at the staging API base URL with your sk_test_ key:

export SOHOPAY_API_KEY="sk_test_..."
export SOHOPAY_BASE_URL="https://staging.api.sohopay.xyz/api/v1"

Sandbox agents receive pre-funded test credit lines and auto-signing support ("signature": "sandbox_auto"), so you can test end-to-end payments without managing cryptographic key shares.

Production / Mainnet

Switch your credentials to the production endpoint with your sk_live_ key:

export SOHOPAY_API_KEY="sk_live_..."
export SOHOPAY_BASE_URL="https://api.sohopay.xyz/api/v1"

Key mainnet requirements:

Merchants must complete KYB verification.
Agent payments require real EIP-712 cryptographic signatures.
Settlements execute with real USDC on Base.

Base RPC & Network Configuration

The SohoPay API abstracts most direct blockchain communication. You only need direct Base RPC access if you verify on-chain settlement receipts yourself or run external event indexers.

Network	Chain ID	Public RPC URL	Block Explorer
Base Sepolia (testnet)	`84532`	`https://sepolia.base.org`	sepolia.basescan.org
Base (mainnet)	`8453`	`https://mainnet.base.org`	basescan.org

Viem Client Example

import { createPublicClient, http } from "viem";
import { baseSepolia } from "viem/chains";

const client = createPublicClient({
  chain: baseSepolia, // Chain ID: 84532
  transport: http("https://sepolia.base.org"),
});

// Verify settlement receipt by hash
const receipt = await client.getTransactionReceipt({
  hash: "0x4d5e...9a0b", // settlement_tx from payment response
});

console.log("Settlement status:", receipt.status);

Public RPC endpoints are rate-limited. For high-volume production integrations, use a dedicated RPC provider (such as Alchemy, QuickNode, or Coinbase Developer Platform) using the chain IDs above.

Test USDC Faucet

Sandbox agents do not need test USDC to start spending — their credit lines are pre-loaded in the sandbox and settlements execute against SohoPay liquidity pools. You only need faucet USDC if you want to test:

Wallet Repayment: Repaying your borrowed principal via the Borrower Portal.
Vault Deposits: Testing collateral deposits via POST /vault/deposit.

How to get testnet USDC:

Navigate to Circle’s official faucet: faucet.circle.com.
Choose Base Sepolia network.
Paste your test wallet address and claim test USDC.
Add the USDC token contract to your wallet:
- Contract Address: 0x036CbD53842c5426634e7929541eC2318f3dCF7e
- Decimals: 6
- Symbol: USDC

API Key Security & Storage

Treat SohoPay API keys with the same security as production database credentials.

Environment Variables: Load keys via .env files locally and ensure .env* is listed in your .gitignore.
Secrets Managers: In deployed production environments, inject keys using secret managers (AWS Secrets Manager, Google Secret Manager, HashiCorp Vault, or Doppler).
Environment Isolation: Keep sandbox (sk_test_) and production (sk_live_) secrets strictly isolated to avoid accidental cross-environment transactions.

Never commit API keys to version control or expose them in client-side code (frontend JavaScript bundles or public AI prompt templates). All API calls must originate from secure backend servers.

Connectivity & Health Troubleshooting

If you encounter connection or authorization issues, check the following:

Health Endpoint: Verify SohoPay API service availability:
curl https://staging.api.sohopay.xyz/health
(Healthy response returns {"status":"ok"} or 200 OK).
Prefix Errors (404 Not Found): Ensure your requests use the /api/v1 prefix (https://staging.api.sohopay.xyz/api/v1/...).
Key Mismatch (401 Unauthorized): Ensure you aren’t passing a sk_test_ key to the production URL or a sk_live_ key to the staging URL.
Rate Limits (429 Too Many Requests): Check the Retry-After header. Agent-level limits are governed by the Policy Service.
Corporate Firewalls: If your network proxy restricts .xyz top-level domains, allowlist *.sohopay.xyz in your egress rules.

Next steps

Quickstart

Run an MCP agent or settle your first x402 payment in 5 minutes.

Authentication

Learn about Bearer authentication, EIP-712 signing, and key rotation.

Borrower Portal

Explore live credit utilization, agent management, and debt repayment.

Getting Started

Merchant Integration

Agent Wallet Setup

Payment Flow

Protocol & Standards

Compliance & Risk

Operational Dashboards

Environment Setup

Environments at a glance

Configure your environment

1. Terminal Pairing

2. Client Configuration

Staging / Sandbox

Production / Mainnet

Base RPC & Network Configuration

Viem Client Example

Test USDC Faucet

How to get testnet USDC:

API Key Security & Storage

Connectivity & Health Troubleshooting

Next steps

Quickstart

Authentication

Borrower Portal

​Environments at a glance

​Configure your environment

​1. Terminal Pairing

​2. Client Configuration

​Staging / Sandbox

​Production / Mainnet

​Base RPC & Network Configuration

​Viem Client Example

​Test USDC Faucet

​How to get testnet USDC:

​API Key Security & Storage

​Connectivity & Health Troubleshooting

​Next steps

Quickstart

Authentication

Borrower Portal

Environments at a glance

Configure your environment

1. Terminal Pairing

2. Client Configuration

Staging / Sandbox

Production / Mainnet

Base RPC & Network Configuration

Viem Client Example

Test USDC Faucet

How to get testnet USDC:

API Key Security & Storage

Connectivity & Health Troubleshooting

Next steps