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

# Borrower onboarding

> Register a borrower, prove their wallet, authorize an agent, and claim a handle.

Onboarding is finished only when the wallet is proved, the agent grant is `ACTIVE`, and the borrower has claimed a handle. Do these steps before the first payment. Discovering a missing step from a 403 during pay is the slow path.

Follow the skill borrower-onboard (`https://agents.sohopay.ai/skills/v1/borrower-onboard.md`) for tool arguments. This page is the sequence and the places you must stop for the borrower.

> [!NOTE]
>
> Profile, bank linking, and credit evaluation that return an `OPEN_URL` handoff happen on a SohoPay page. Tell the borrower what the page is for. Do not ask for a legal name or date of birth in chat, and do not invent a URL.

![Borrower onboarding flow from hosted MCP connection through wallet proof, workload-key registration, agent authorization, and handle claim](/images/onboarding-light.png)

## Sequence

**1. Read context**

Call `get_context`. It reports identity, credit, authorization, and the likely next step. It does not approve a payment; `prepare_x402_payment` rechecks at spend time.

**2. Register the terminal**

Call `register_borrower`. Store `operational_agent_id` and `terminal_id`. This call is idempotent.

**3. Prove the wallet**

`CONNECT_WALLET` means the borrower has no wallet yet — they connect one in the browser. `PROVE_WALLET` means the wallet is registered and only the proof is missing.

For `PROVE_WALLET`: call `request_signature_challenge`, stop, and have the borrower sign the EIP-712 challenge in their wallet. Then `submit_signature`. Use a new idempotency key for the submit. See [EIP-712](/protocol/eip-712.md).

**4. Take a borrower token**

Call `request_borrower_token` with the scopes the rest of onboarding needs, including `credit:facility:accept` on the first grant. Do not ask the borrower to approve this token in chat.

**5. Register the workload key**

Generate the Ed25519 key locally, sign the proof of possession, and call `register_agent_workload_key`. See [Key management](/guides/key-management.md).

**6. Authorize the agent**

Call `authorize_agent`. Open the returned `consent_url` as-is (`https://staging.sohopay.ai/agent/authorize` on staging, `https://app.sohopay.ai/agent/authorize` on production). The borrower signs `AgentAuthorizationGrant` in the browser. The page submits the signature.

Poll `get_agent_authorization` every 5 seconds for up to 2 minutes until the grant is `ACTIVE`. Do not invent a payment to force this step. The grant carries the per-payment, daily, and merchant limits the agent must live inside.

**7. Claim a handle**

When the next action is `claim_handle`, call `check_handle_availability`, stop, and ask the borrower to choose one of `suggested_handles`. Confirm the exact string, then `claim_handle`. The borrower is not onboarded without a handle.

## If pay starts before this finishes

`X402_AGENT_KEY_NOT_REGISTERED` and `AGENT_AUTHORIZATION_REQUIRED` mean onboarding was skipped. Finish the steps above, then retry the **same** order with the **same** payment idempotency key.

## Next steps

> [card] [Payment flow](/guides/payment-flow.md)
>
> Spend after the grant is active.

> [card] [Repayment](/guides/repayment.md)
>
> Pay the facility down.
