Quickstart

Welcome to SohoPay! SohoPay provides non-custodial on-chain credit infrastructure for AI agents on Base Sepolia. Agents can autonomously purchase APIs, compute, and services from merchants using the x402 (HTTP 402 Payment Required) protocol. Choose your preferred path below to get started in minutes:

Option A: AI Agent Setup via MCP (Recommended)
Option B: Developer REST API & SDK

If you use Cursor IDE, Claude Desktop, Windsurf, or custom agent frameworks, connect SohoPay directly using the Model Context Protocol (MCP) in under 2 minutes.

Pair your agent via CLI login

Run the one-click pairing command in your terminal. This opens a browser window to link your social account (GitHub, LinkedIn, or X) and verify your test wallet with an EIP-712 signature:

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

This automatically provisions your terminal-1 agent with an active sandbox credit line. No manual key management or gas funds required!

Configure your AI client

Add the SohoPay MCP server configuration to your preferred tool. You can connect directly via the hosted Remote MCP server (recommended, zero local dependencies) or run via local stdio:

{
  "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"
      }
    }
  }
}

Test spending in your AI Chat

Open your AI assistant chat and ask:

“Check my SohoPay available credit balance and agent status.”

Your AI agent will execute the get_balance MCP tool and return your current available test credit.

Monitor & control in the Borrower Portal

Open the SohoPay Borrower Portal to:

View your real-time Available Credit and Outstanding Debt.
Inspect active agents under My Agents.
Instant Pause / Resume switch to immediately block or restore agent spending at the gateway.
Test zero-gas wallet repayment.

Success! Your AI agent is now equipped with autonomous credit rails.

If you are building custom backend services, merchant checkout, or programmatic agent platforms, follow this 5-minute REST API walkthrough.

Create a sandbox account & get API key

Sign in to the SohoPay Dashboard.
Navigate to Settings → API Keys → Create key. Sandbox keys start with sk_test_.
Save your key in an environment variable:

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

Never embed API keys in client-side code or commit them to public repositories. See Authentication & Security.

Provision an agent with a credit line

Provision an operational agent with a 50 USDC sandbox credit line:

curl -X POST https://staging.api.sohopay.xyz/api/v1/agents \
  -H "Authorization: Bearer $SOHOPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "mch_sandbox_demo",
    "name": "my-first-agent",
    "credit_limit": "50.00",
    "daily_limit": "10.00",
    "operator_acknowledgment": true
  }'

import { SohoPay } from "@sohopay/sdk";

const sohopay = new SohoPay({
  apiKey: process.env.SOHOPAY_API_KEY,
  baseUrl: "https://staging.api.sohopay.xyz/api/v1",
});

const agent = await sohopay.agents.create({
  merchantId: "mch_sandbox_demo",
  name: "my-first-agent",
  creditLimit: "50.00",
  dailyLimit: "10.00",
  operatorAcknowledgment: true,
});

console.log("Agent created:", agent.agentId, agent.walletAddress);

import os
from sohopay import SohoPay

sohopay = SohoPay(
    api_key=os.environ["SOHOPAY_API_KEY"],
    base_url="https://staging.api.sohopay.xyz/api/v1",
)

agent = sohopay.agents.create(
    merchant_id="mch_sandbox_demo",
    name="my-first-agent",
    credit_limit="50.00",
    daily_limit="10.00",
    operator_acknowledgment=True,
)

print("Agent created:", agent.agent_id, agent.wallet_address)

You will receive a 201 Created response:

Response

{
  "agent_id": "agt_7d1e5b2f",
  "merchant_id": "mch_sandbox_demo",
  "name": "my-first-agent",
  "wallet_address": "0x8ba1f109551bd432803012645ac136ddd64dba72",
  "status": "active",
  "credit_limit": "50.00",
  "daily_limit": "10.00",
  "available_credit": "50.00",
  "created_at": "2026-08-22T10:15:00Z"
}

Create an order and submit an x402 payment

Create a 1.00 USDC order for your agent, then submit the payment. In the sandbox, SohoPay auto-signs so you can test the end-to-end loop without implementing local EIP-712 key management yet:

# 1. Create test order
curl -X POST https://staging.api.sohopay.xyz/api/v1/orders \
  -H "Authorization: Bearer $SOHOPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "mch_sandbox_demo",
    "agent_id": "agt_7d1e5b2f",
    "amount": "1.00"
  }'

# 2. Submit payment (sandbox auto-signs)
curl -X POST https://staging.api.sohopay.xyz/api/v1/payments \
  -H "Authorization: Bearer $SOHOPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "ord_9f8e7d6c",
    "agent_id": "agt_7d1e5b2f",
    "signature": "sandbox_auto"
  }'

const order = await sohopay.orders.create({
  merchantId: "mch_sandbox_demo",
  agentId: agent.agentId,
  amount: "1.00",
});

const payment = await sohopay.payments.submit({
  orderId: order.orderId,
  agentId: agent.agentId,
  signature: "sandbox_auto",
});

order = sohopay.orders.create(
    merchant_id="mch_sandbox_demo",
    agent_id=agent.agent_id,
    amount="1.00",
)

payment = sohopay.payments.submit(
    order_id=order.order_id,
    agent_id=agent.agent_id,
    signature="sandbox_auto",
)

Verify on-chain settlement & borrower balance

Poll the payment until settled (usually under 2 seconds on Base Sepolia):

curl https://staging.api.sohopay.xyz/api/v1/payments/pay_5c4b3a29 \
  -H "Authorization: Bearer $SOHOPAY_API_KEY"

Response

{
  "payment_id": "pay_5c4b3a29",
  "order_id": "ord_9f8e7d6c",
  "status": "settled",
  "amount": "1.00",
  "settlement_tx": "0x4d5e...9a0b",
  "settled_at": "2026-08-22T10:16:02Z"
}

You can view the settlement transaction directly on Sepolia Basescan or track live debt updates in the Borrower Portal.

Test agent safety controls (Pause / Resume)

As a borrower or platform operator, you can instantly pause an agent’s spending. The gateway blocks any subsequent payment authorization immediately:

# Pause agent
curl -X POST https://staging.api.sohopay.xyz/api/v1/agents/agt_7d1e5b2f/pause \
  -H "Authorization: Bearer $SOHOPAY_API_KEY"

# Resume agent
curl -X POST https://staging.api.sohopay.xyz/api/v1/agents/agt_7d1e5b2f/resume \
  -H "Authorization: Bearer $SOHOPAY_API_KEY"

That’s it! You have provisioned an agent, settled an on-chain x402 payment, and verified instant spending controls.

Key Environments & Resources

Service	Staging URL	Purpose
Hosted MCP Server	`https://staging.mcp.sohopay.xyz/mcp`	Direct SSE/HTTP endpoint for Claude Desktop, Cursor, Windsurf, and remote MCP clients
API Gateway	`https://staging.api.sohopay.xyz/api/v1`	All REST endpoints and MCP gateway calls
Borrower Portal	`https://staging.borrower.sohopay.xyz/`	View credit balances, manage agents, and repay debt
Merchant Dashboard	`https://staging.sohopay.xyz`	Merchant API keys, order feeds, and payout configuration
Network	Base Sepolia (Chain ID: 84532)	Testnet smart contracts and USDC settlement

Next: choose your integration path

Pick the guide that matches what you are building:

Agent Operator Setup

Run autonomous agents with credit lines, vault collateral, and EIP-712 signing.

Merchant Integration

Accept agent payments over HTTP 402, manage allowlists, and receive USDC payouts.

Borrower Portal Guide

Learn how to monitor credit utilization, pause agents, and repay principal from your wallet.

Getting Started

Merchant Integration

Agent Wallet Setup

Payment Flow

Protocol & Standards

Compliance & Risk

Operational Dashboards

Key Environments & Resources

Next: choose your integration path

Agent Operator Setup

Merchant Integration

Borrower Portal Guide

​Key Environments & Resources

​Next: choose your integration path

Agent Operator Setup

Merchant Integration

Borrower Portal Guide

Key Environments & Resources

Next: choose your integration path