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 for tool arguments. This page is the sequence and the places you must stop for the borrower.
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.
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.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.6
Authorize the agent
Call
authorize_agent. Open the returned consent_url as-is (https://staging.sohopay.xyz/agent/authorize on staging). 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
Payment flow
Spend after the grant is active.
Repayment
Pay the facility down.