Agent Setup

This guide covers everything you need to set up autonomous agents on SohoPay: how agent credit lines work, the operator liability model, how to provision agents via MCP or REST API, and how to enforce instant spend controls.

What is an agent?

An agent is any autonomous program that spends funds on your behalf — an LLM-driven development assistant (Cursor, Claude, Windsurf), a data-gathering pipeline, or an automated workflow bot. In SohoPay, each agent receives:

A dedicated Base wallet identity.
A revolving credit line backed by your credit facility or vault collateral.
Granular spending limits (credit_limit and daily_limit).
Payment rail access over x402 with ~1s USDC settlement.

Credit line vs. prefunded wallets

SohoPay agents run on revolving credit lines rather than prefunded balances:

Dimension	Credit line (SohoPay)	Prefunded wallet
Capital efficiency	One credit facility/vault backs multiple agents	Idle funds locked across individual wallets
Blast radius	Capped strictly by `credit_limit` and `daily_limit`	The entire wallet balance is exposed
Maintenance	Zero-maintenance revolving credit	Requires recurring manual balance top-ups
Spend controls	Enforced at the gateway on every payment	None beyond the wallet balance
Emergency freeze	Instant pause via API or portal	Requires on-chain fund sweeping transactions

Operator liability

As the agent operator, you remain legally and financially liable for every transaction your agents execute. Merchants receive 100% of their order settlement instantly; there is no chargeback mechanism. Because of this, programmatic agent creation requires an explicit acknowledgment:

"operator_acknowledgment": true

operator_acknowledgment represents a binding legal acceptance of liability up to the agent’s assigned credit limit. See Operator Liability before deploying production agents.

Choose your setup method

Option A: Fast AI Agent Setup via MCP (Recommended)
Option B: Programmatic REST API Provisioning

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

1. Pair your terminal

Run the login command in your terminal:

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

Follow the browser prompt to log in with GitHub, LinkedIn, or X and verify your test wallet.

Zero-Configuration: This automatically adopts and provisions your terminal-1 operational agent with an active sandbox credit line. No manual API calls required!

2. Inspect your agent

Once logged in, your agent appears immediately in the Borrower Portal, where you can rename it, monitor spending, or toggle pause controls.

If you operate an autonomous backend platform or multi-agent system, provision agents programmatically via the REST API:

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

Provision an agent

curl -X POST https://staging.api.sohopay.xyz/api/v1/agents \
  -H "Authorization: Bearer $SOHOPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-agent-procurement-01" \
  -d '{
    "merchant_id": "mch_sandbox_demo",
    "name": "procurement-agent",
    "credit_limit": "500.00",
    "daily_limit": "100.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: "procurement-agent",
  creditLimit: "500.00",
  dailyLimit: "100.00",
  operatorAcknowledgment: true,
});

console.log("Agent provisioned:", 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="procurement-agent",
    credit_limit="500.00",
    daily_limit="100.00",
    operator_acknowledgment=True,
)

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

Successful response (`201 Created`):

{
  "agent_id": "agt_3f9a1c8e",
  "merchant_id": "mch_sandbox_demo",
  "name": "procurement-agent",
  "wallet_address": "0x8ba1f109551bd432803012645ac136ddd64dba72",
  "status": "active",
  "credit_limit": "500.00",
  "daily_limit": "100.00",
  "available_credit": "500.00",
  "created_at": "2026-08-22T10:15:00Z"
}

Spend limits & velocity controls

Every agent is protected by two distinct limit boundaries:

credit_limit — The maximum outstanding balance the agent can carry at any time. Consumes total facility or vault capacity.
daily_limit — The maximum cumulative amount the agent can spend in a rolling 24-hour window, regardless of available credit.

Best Practice: Always set daily_limit to standard expected daily spend, rather than matching credit_limit. A 500 USDC credit line with a 50 USDC daily limit ensures a misbehaving agent cannot burn through its entire allocation in a short spike.

Agent safeguards & controls

SohoPay provides real-time lifecycle controls. Actions take effect at the gateway immediately:

1. Pause an agent (Freeze spending)

If an agent misbehaves or requires maintenance, pause it. Any subsequent payment authorization requests will be rejected by the gateway in < 5s:

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

2. Resume an agent

When ready, re-enable the agent. The gateway revalidates facility standing and restores authorization capabilities:

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

3. Update agent nickname

Assign friendly labels to distinguish multiple agents in your fleet:

curl -X PATCH https://staging.api.sohopay.xyz/api/v1/agents/agt_3f9a1c8e/nickname \
  -H "Authorization: Bearer $SOHOPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nickname": "Production Indexer Bot"
  }'

All of these controls can also be operated directly with a single click in the Borrower Portal.

Common error codes

Error Code	HTTP Status	Description	Action
`INVALID_AGENT`	400	Missing `operator_acknowledgment: true` or `daily_limit` exceeds `credit_limit`.	Ensure the request payload conforms to required spend constraints.
`INSUFFICIENT_CREDIT`	402	Requested credit limit exceeds remaining facility or vault capacity.	Lower requested limit or deposit additional collateral.
`AGENT_NOT_OWNED`	403	Attempted to pause or modify an agent that belongs to another borrower account.	Verify your credentials and agent ID.

Next steps

Key Management

Understand how MPC key shares and EIP-712 signing operate.

Vault & Funding

Manage USDC collateral deposits and borrowing capacity.

Payment Flow

Follow the complete order-to-settlement lifecycle over x402.

Getting Started

Merchant Integration

Agent Wallet Setup

Payment Flow

Protocol & Standards

Compliance & Risk

Operational Dashboards

What is an agent?

Credit line vs. prefunded wallets

Operator liability

Choose your setup method

1. Pair your terminal

2. Inspect your agent

Provision an agent

Successful response (`201 Created`):

Spend limits & velocity controls

Agent safeguards & controls

1. Pause an agent (Freeze spending)

2. Resume an agent

3. Update agent nickname

Common error codes

Next steps

Key Management

Vault & Funding

Payment Flow

​What is an agent?

​Credit line vs. prefunded wallets

​Operator liability

​Choose your setup method

​1. Pair your terminal

​2. Inspect your agent

​Provision an agent

​Successful response (201 Created):

​Spend limits & velocity controls

​Agent safeguards & controls

​1. Pause an agent (Freeze spending)

​2. Resume an agent

​3. Update agent nickname

​Common error codes

​Next steps

Key Management

Vault & Funding

Payment Flow

What is an agent?

Credit line vs. prefunded wallets

Operator liability

Choose your setup method

1. Pair your terminal

2. Inspect your agent

Provision an agent

Successful response (`201 Created`):

Spend limits & velocity controls

Agent safeguards & controls

1. Pause an agent (Freeze spending)

2. Resume an agent

3. Update agent nickname

Common error codes

Next steps