SohoPay has two caller types, and they do not share a key format. Agents never see the merchant API key. Merchants never receive the agent’s workload key.

​
Agents

The host connects to https://staging.mcp.sohopay.xyz/mcp with OAuth 2.1. Dynamic client registration is enabled on staging for Cursor, Claude, and loopback redirects. After the borrower grants access, the host calls MCP tools with a borrower token. The token is a JWT whose scopes are limited by how far onboarding has progressed. Request the scopes the next tool needs. prepare_x402_payment requires all three of spend:intent:create, policy:evaluate, and signing:request. Onboarding also needs borrower:token, credit:facility:accept, agent:key:register when rotating a key, handle:claim, and repayment:execute when repaying. Refresh the borrower token when it is within about three minutes of expiry. A scope list on an identity call is not a refresh signal.
Do not put a borrower seed or private key in the agent, the MCP config, or a skill. Wallet proof, the agent grant, and repayment are EIP-712 signatures the borrower makes in their own wallet. See Key management.

​
Merchants

Send Authorization: Bearer <credential> on facilitator routes.
  • A merchant user JWT from the SohoPay app, or
  • An API key shaped sk_live_ plus a base64url secret, bound to one merchant UUID.
There is no sk_test_ prefix. Staging keys use sk_live_ too. Keys are issued when SohoPay provisions the merchant. They are not minted from a public dashboard signup. Capture requires the permission x402:settle:create. Verify and status polls require x402:settle:read. Machine callers using an API key satisfy the capture step-up on that route only.
GET /api/v1/facilitator/supported and GET /api/v1/facilitator/health are the public discovery and liveness routes.

​
Idempotency

Send Idempotency-Key: <uuid v4> on mutating calls, including capture and MCP writes. The same key with the same body replays the first result. The same key with a different body is a conflict. A 402 payment keeps one idempotency key for its orderRef across retries.

​
Identifiers

Borrowers, merchants, and operational agents are UUIDs. On-chain ids are bytes32 values derived from those UUIDs. Store operational_agent_id from register_borrower and pass it when the borrower has more than one terminal.

​
Next steps

Borrower onboarding

The stops that need the borrower in person.

Merchant integration

Where the API key is used.