Most integrations are one of two callers. A product that both spends and charges implements both, and they stay separate: the agent never calls the facilitator, and the merchant never calls prepare_x402_payment.

​
Agent

You are an agent host, or you are embedding SohoPay so an agent can buy APIs, data, or compute.
  1. Connect hosted MCP. Agent setup.
  2. Finish borrower onboarding, including the wallet proof, the agent grant, and a handle. Borrower onboarding.
  3. On each HTTP 402, prepare, sign, and retry. Payment flow.
  4. When the borrower wants to pay the facility down, open the repay consent URL. Repayment.
The behavior contract for agents is the skill set at https://agents.sohopay.xyz/skills/v1/. These docs describe the same flow without replacing those skills.

​
Merchant

You run a resource server that should charge agents.
  1. Get a merchant account. Merchant onboarding.
  2. Return 402, then verify and capture the voucher. Merchant integration.
  3. Poll until CONFIRMED before you fulfill. Settlements.
Your merchant must be ACTIVE in SohoMerchantRegistry. The fee on a captured payment is deducted from your payout. See Fees.

​
What we do not offer as an integration path

  • A REST SDK (@sohopay/sdk, sohopay on PyPI) that creates agents and orders.
  • An operator API that deposits vault collateral and then provisions MPC wallets.
  • A local stdio MCP server you clone and run.
  • Merchant settlement webhooks. You poll.

​
Next steps

Quickstart

The shortest version of each path.

Protocol: x402

What the 402 body and the voucher mean.