Agent Setup

This is the landing page for the agent track. It covers what an agent is in SohoPay terms, how credit lines compare to prefunded wallets, the operator liability model, how agent keys are generated, and the API call that creates your first agent. Budget ~2–3 days for a full agent integration.

What is an agent?

An agent is any autonomous program that spends money on your behalf — an LLM-driven shopping assistant, a data-pipeline worker buying API calls, a trading bot paying for feeds. In SohoPay, each agent gets its own on-chain wallet on Base, its own credit line drawn against your vault collateral, and its own spending limits. Payments happen over x402 with ~1s USDC settlement. You (the operator) create agents, fund the vault that backs them, and remain liable for everything they spend.

Credit vs. prefunded

SohoPay agents run on credit lines rather than prefunded balances. The difference matters for capital efficiency and blast radius:

	Credit line (SohoPay)	Prefunded wallet
Capital at rest	One vault deposit backs many agents	Each wallet holds idle USDC
Blast radius if key misused	Capped by `credit_limit` and `daily_limit`	Entire wallet balance
Topping up	Not needed — credit revolves	Manual transfers per wallet
Revocation	Instant — credit line frozen server-side	Must sweep funds out
Spend controls	Policy Service enforces limits per payment	None beyond the balance itself

Your vault balance is your total borrowing capacity: the sum of all agent credit limits cannot exceed what your vault collateral can back. See Vault & Funding.

Operator liability

The operator is liable for every transaction their agents make. There is no chargeback path against the merchant — merchants are always paid in full, and the 5% fee is charged to your credit line. Because of this, agent creation requires an explicit operator_acknowledgment: true field. Requests without it are rejected with a 400.

Treat operator_acknowledgment as a legal act, not boilerplate. By setting it you accept liability for the agent’s spend up to its credit limit. Read Operator Liability before creating mainnet agents.

Key generation

By default, agent keys are generated inside SohoPay’s MPC escrow. The key is born as shares inside the MPC signing infrastructure — the complete private key never exists in one place, and you never receive or handle raw key material. Every payment signature requires 2-of-3 shares, including the Policy Service share, so a stolen agent share alone cannot move funds. This is the only key option available today. See Key Management for rotation, disaster recovery, and best practices.

Create an agent

POST /agents provisions the MPC wallet and attaches the credit line in one call:

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

const agent = await sohopay.agents.create({
  merchantId: "mch_sandbox_demo",
  name: "procurement-agent",
  creditLimit: "500.00",
  dailyLimit: "100.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="procurement-agent",
    credit_limit="500.00",
    daily_limit="100.00",
    operator_acknowledgment=True,
)

print(agent.agent_id, agent.wallet_address)

A successful call returns 201 with the new agent:

Response

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

An agent.created event is also delivered to your webhook endpoint.

Credit limit vs. daily limit

The two limits solve different problems:

credit_limit — the maximum outstanding balance the agent can carry at any time. It caps your total liability for this agent and consumes vault borrowing capacity.
daily_limit — the maximum the agent can spend in a rolling 24-hour window, regardless of remaining credit. It caps velocity, so a compromised or misbehaving agent burns through funds slowly enough for you to notice and revoke it.

Set daily_limit to what the agent needs on a normal day, not to its credit limit. A 500 USDC credit line with a 100 USDC daily limit means a runaway agent takes five days to exhaust its credit instead of five minutes.

Error cases

Code	Status	Meaning	Fix
`INSUFFICIENT_CREDIT`	402	Your vault collateral cannot back the requested `credit_limit` on top of existing agents.	Deposit more collateral (Vault & Funding) or request a lower limit.
`INVALID_AGENT`	400	Malformed request — missing `operator_acknowledgment`, non-positive limits, or `daily_limit` exceeding `credit_limit`.	Correct the request body; the `message` field names the offending field.

All errors use the standard envelope with a request_id — see Errors.

Next steps

Key Management

How MPC agent keys work, rotation, and disaster recovery.

Vault & Funding

Deposit collateral to back credit lines and manage withdrawals.

Payment Flow

How your agent’s payments sign and settle over x402.

Getting Started

Merchant Integration

Agent Wallet Setup

Payment Flow

Protocol & Standards

Compliance & Risk

Operational Dashboards

What is an agent?

Credit vs. prefunded

Operator liability

Key generation

Create an agent

Credit limit vs. daily limit

Error cases

Next steps

Key Management

Vault & Funding

Payment Flow

​What is an agent?

​Credit vs. prefunded

​Operator liability

​Key generation

​Create an agent

​Credit limit vs. daily limit

​Error cases

​Next steps

Key Management

Vault & Funding

Payment Flow

What is an agent?

Credit vs. prefunded

Operator liability

Key generation

Create an agent

Credit limit vs. daily limit

Error cases

Next steps