Quickstart

Use staging. Production settlement is not enabled, and there is no separate sandbox host. Pick the track that matches your job: an agent that pays, or a merchant that gets paid.

Agent
Merchant

The agent path is the hosted MCP server plus the skills on the CDN. SohoPay does not ship a local MCP binary or a login CLI.

Install the staging skills

Follow setup-staging, or start from https://staging.sohopay.xyz/install.Then connect the host with mcp-connect-staging. The server URL is:

https://staging.mcp.sohopay.xyz/mcp

The host completes OAuth in the browser. You do not paste a borrower private key into the agent.

Onboard the borrower

The skill borrower-onboard is the procedure. In short: register_borrower (keep operational_agent_id and terminal_id), prove the wallet with an off-device EIP-712 signature, register an Ed25519 workload key, open the agent-grant consent URL until the grant is ACTIVE, and claim_handle. The borrower is not onboarded without a handle.Details and the stops where a person must act are on Borrower onboarding.

Pay a 402

When a merchant returns HTTP 402, call prepare_x402_payment for that order. On VOUCHER_ISSUED, sign the voucher with @sohopay/agent-signer and send PAYMENT-SIGNATURE back to the merchant. Keep the same payment idempotency key for the same orderRef.The full sequence is Payment flow.

Merchant accounts are provisioned by SohoPay after KYB. Email support@sohopay.xyz for a staging merchant and an sk_live_ API key. The key is live-prefixed even on staging; there is no sk_test_ key.

Advertise x402

Your resource server answers unpaid requests with HTTP 402 and a credit-scheme payment requirement for eip155:84532. See x402.

Capture the voucher

When the agent retries with PAYMENT-SIGNATURE, submit that envelope to the facilitator. x402Version must be 2.

curl -X POST https://staging.api.sohopay.xyz/api/v1/facilitator/capture \
  -H "Authorization: Bearer $SOHO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d @capture.json

A 200 body includes receipt.paymentId. That id is the poll key. Do not treat capture as final delivery unless you have explicitly accepted capture-then-deliver risk.

Poll until CONFIRMED

curl https://staging.api.sohopay.xyz/api/v1/facilitator/settle/status/by-payment/$PAYMENT_ID \
  -H "Authorization: Bearer $SOHO_API_KEY"

Poll about every 2 seconds. Release the resource only when status is CONFIRMED. CREATED and SUBMITTED are still pending. There is no POST /settle and no settlement webhook.Status meanings are on Settlements.

Getting Started

Merchant Integration

Agents

Protocol

Compliance

Next steps

Environment setup

Authentication

​Next steps

Environment setup

Authentication

Next steps