Quickstart

This guide takes you from zero to a settled sandbox payment in about 5 minutes. No USDC, no wallet setup, and no key management required — the sandbox runs on Base Sepolia with test funds.

Create a sandbox account

Sign up at the SohoPay Dashboard and choose Developer sandbox. Sandbox accounts skip KYB and come pre-loaded with test vault collateral.

Generate an API key

In the dashboard, go to Settings → API Keys → Create key. Sandbox keys start with sk_test_. Copy it once — it is not shown again.

export SOHOPAY_API_KEY="sk_test_..."

Never embed API keys in client-side code or commit them to git. Store them in environment variables or a secrets manager. See Authentication & Security.

Create an agent with a credit line

This provisions an agent wallet inside SohoPay’s MPC infrastructure and attaches a 50 USDC test credit line:

curl -X POST https://api-sandbox.sohopay.xyz/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 });

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.agentId, agent.walletAddress);

from sohopay import SohoPay

sohopay = SohoPay(api_key=os.environ["SOHOPAY_API_KEY"])

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.agent_id, agent.wallet_address)

You should get back a 201 with the new agent:

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 pay it

Create a 1 USDC order for your agent, then submit the payment. In the sandbox, SohoPay signs on the agent’s behalf so you can test the full flow without implementing EIP-712 signing yet:

# 1. Create the order
curl -X POST https://api-sandbox.sohopay.xyz/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 the payment (sandbox auto-signs)
curl -X POST https://api-sandbox.sohopay.xyz/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 the settlement

Poll the payment until it settles (usually under 2 seconds in sandbox):

curl https://api-sandbox.sohopay.xyz/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"
}

That’s it — you settled your first payment. Open the settlement_tx hash on Sepolia Basescan to see it on-chain, or watch it appear in the Live Feed.

Next: choose your integration path

Now that you have a working API key, pick the track that matches what you’re building:

Merchant Integration

Accept agent payments. KYB, allowlists, settlements, webhooks. ~3–5 days.

Agent Setup

Run agents with credit lines. Keys, vault funding, limits. ~2–3 days.

Full End-to-End

Both sides of the flow for platforms. ~5–7 days.

Getting Started

Merchant Integration

Agent Wallet Setup

Payment Flow

Protocol & Standards

Compliance & Risk

Operational Dashboards

Next: choose your integration path

Merchant Integration

Agent Setup

Full End-to-End

​Next: choose your integration path

Merchant Integration

Agent Setup

Full End-to-End

Next: choose your integration path