> ## Documentation Index
> Fetch the complete documentation index at: /llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Connect a hosted MCP agent or capture an x402 payment on SohoPay staging.

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.

> [tab] Agent
>
> 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.
>
> **1. Install the staging skills**
>
> Follow setup-staging (`https://agents.sohopay.ai/skills/v1/setup-staging.md`), or start from `https://staging.sohopay.ai/install`.
>
> Then connect the host with mcp-connect-staging (`https://agents.sohopay.ai/skills/v1/mcp-connect-staging.md`). The server URL is:
>
> ```text
> https://staging.mcp.sohopay.ai/mcp
> ```
>
> The host completes OAuth in the browser. You do not paste a borrower private key into the agent.
>
> **2. Onboard the borrower**
>
> The skill borrower-onboard (`https://agents.sohopay.ai/skills/v1/borrower-onboard.md`) 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](/guides/borrower-onboarding.md).
>
> **3. 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`](/sdks/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](/guides/payment-flow.md).

> [tab] Merchant
>
> Merchant accounts are provisioned by SohoPay after KYB. Email `support@sohopay.ai` for a staging merchant and an `sk_live_` API key. The key is live-prefixed even on staging; there is no `sk_test_` key.
>
> **1. Advertise x402**
>
> Your resource server answers unpaid requests with HTTP 402 and a credit-scheme payment requirement for `eip155:84532`. See [x402](/protocol/x402.md).
>
> **2. Capture the voucher**
>
> When the agent retries with `PAYMENT-SIGNATURE`, submit that envelope to the facilitator. `x402Version` must be `2`.
>
> ```bash
> curl -X POST https://staging.api.sohopay.ai/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.
>
> **3. Poll until CONFIRMED**
>
> ```bash
> curl https://staging.api.sohopay.ai/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](/guides/settlements-payouts.md).

## Next steps

> [card] [Environment setup](/environment-setup.md)
>
> Hosts, chain id, and staging contracts.

> [card] [Authentication](/authentication.md)
>
> How agents and merchants authenticate.
