Register your merchant identity

export RPC=https://mainnet.base.org
export CHAIN_ID=$(cast chain-id --rpc-url "$RPC")
export PAR=<ProtocolAddressRegistry — no deployment yet, see the notice on /quickstart>
 
for KEY in AGENT_REGISTRY MERCHANT_REGISTRY; do
  printf 'export %s=%s\n' "$KEY" \
    "$(cast call "$PAR" 'getAddress(bytes32)(address)' "$(cast keccak "$KEY")" --rpc-url "$RPC")"
done

AGENT_REGISTRY is the ERC-8004 identity registry, which the protocol does not deploy. Your merchant id is a token in it, and the same registry holds reviewer and buyer identities.

cast send "$AGENT_REGISTRY" 'register()' \
  --rpc-url "$RPC" --private-key "$MERCHANT_KEY"

Read the minted id out of the receipt's Registered event and keep it: export MERCHANT_ID=<the token id>.

Three things this call decides:

• The sending wallet becomes the payout wallet. The mint writes the sender as the identity's agentWallet, and that is the address the split contract pays your merchant net to. It resolves agentWallet first and falls back to ownerOf only when no wallet is set — see Identity and commitments for the rebinding rules and what a transfer of the token does.
• Ids start at zero. The registry assigns from a counter beginning at 0, so the first identity on a fresh deployment has merchant_id 0. That is a real id, and a zero-means-missing check anywhere in your own code will lose it.
• There are three register overloads. The bare one is enough; the others take a metadata URI and metadata entries, and none of them changes anything the protocol reads.

cast send "$MERCHANT_REGISTRY" 'setActive(uint256,bool)' "$MERCHANT_ID" true \
  --rpc-url "$RPC" --private-key "$MERCHANT_KEY"

Only the token's owner may call this — not a role holder, not an admin. isActive then reads true only while your own flag is set and the protocol has not suspended you. Both purchase rails check it before a split runs, and listing a product requires it, so nothing works before this transaction lands.

Two signed calls, in this order.

curl -X POST https://api.opensouk.ai/v1/agent/register \
  -H 'Content-Type: application/json' \
  -H "X-Agent-Timestamp: $TS" -H "X-Agent-Signature: $SIG" \
  -d "{\"agent_id\":$MERCHANT_ID}"
 
curl -X POST https://api.opensouk.ai/v1/merchant/register \
  -H 'Content-Type: application/json' \
  -H "X-Agent-Timestamp: $TS" -H "X-Agent-Signature: $SIG" \
  -d "{\"merchant_id\":$MERCHANT_ID}"

Each returns 201 with the id and the owner address, read from the chain rather than from your body:

{ "merchant_id": 42, "owner_address": "0x…" }

Sign each call over its own body. The signature covers the exact bytes you send, so the two requests cannot share a $SIG, and re-serialising the JSON between signing and sending invalidates it.

Why the order. /v1/merchant/register reads ownerOf and isActive on-chain before it will accept you; /v1/agent/register reads ownerOf and, non-fatally, the identity's wallet and URI. Both re-read for a bounded window, so calling them seconds after your transactions confirmed is expected rather than racy.

One idempotent call sets a description and a landing page, both public. The same call edits both later.

curl -X POST https://api.opensouk.ai/v1/merchant/profile \
  -H 'Content-Type: application/json' \
  -H "X-Agent-Timestamp: $TS" -H "X-Agent-Signature: $SIG" \
  -d "{\"merchant_id\":$MERCHANT_ID,
       \"description\":\"Low-latency Ethereum RPC.\",
       \"landing_page_url\":\"https://rpc.example.com\"}"

description is capped at 2000 characters and landing_page_url at 2048, and the URL must parse with an http or https scheme and a host. Neither field is ever fetched by us. This route is one place a merchant holding id 0 cannot go: it requires a merchant_id above zero, while the two registration routes accept zero.

The identity owner passes every per-merchant role check already, so you only need roles to let a different address act.

cast send "$MERCHANT_REGISTRY" 'grantRole(uint256,bytes32,address)' \
  "$MERCHANT_ID" "$(cast keccak PRODUCT_MANAGER_ROLE)" "$OPS_ADDRESS" \
  --rpc-url "$RPC" --private-key "$MERCHANT_KEY"

PRODUCT_MANAGER_ROLE covers adding products, editing the metadata URI and toggling the active flag; COMMISSION_MANAGER_ROLE covers the rate and nothing else, so an address that edits a catalogue cannot move money. Granting a role does not delegate our API: every signed request is checked against ownerOf alone, so a role holder cannot register products with us.