List a product

A listing is two writes. addProduct puts the terms on-chain — the commission rate the split reads, the product type, and the active flag. One signed request attaches the four fields a buyer's agent searches on: name, description, category and the endpoint it pays. What the product record holds, and what product type changes downstream, are on Identity and commitments. Nothing is deployed on a public chain yet — see Quickstart.

What you will build

One product on-chain under your merchant id, created active with a commission rate, and the same product in our records with its name, description, category and purchase endpoint.

Before you start

• An active merchant identity, registered with us — Register your merchant identity. Both writes fail without it, and one of them fails after you have paid gas.
• A funded wallet, the identity owner's, for one transaction and for the signature on the API call.
• cast, and a curl that can sign a request — see The API for the signature construction. The snippets assume $TS and $SIG.

The metadata lives at api.opensouk.ai.

Prompt mode

List a product for our merchant identity on the OpenSouk protocol on Base mainnet.

1. Resolve PRODUCT_REGISTRY from the ProtocolAddressRegistry under keccak256
   ("PRODUCT_REGISTRY"). Do not hardcode it.
2. Choose a productId: any bytes32, unique per merchant. Use keccak256 of a stable slug so
   the id is reproducible from the slug.
3. Send addProduct(merchantId, productId, commissionBps, productType, productCardURI) from
   the identity owner's wallet. commissionBps is basis points out of 10000. productType is
   a uint8 enum: 0 is Repeat, 1 is OneOff, and it can never be changed afterwards. There is
   no cashback argument and no active argument — the product is created active.
4. POST /v1/merchant/product signed, with merchant_id, product_id, endpoint_url, name,
   description and category. endpoint_url must be an http or https URL with a host, and it
   is the URL a buyer's agent will actually call to pay. The commission rate, the active
   flag, the product type and the card URI are read from the chain by this route and are
   NOT taken from the body.
5. Verify with an unsigned GET /v1/merchant/product?merchant_id=…&product_id=…

Do step 3 before step 4: the API refuses metadata for a product it cannot find on-chain.

Manual mode

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>
 
export PRODUCT_REGISTRY=$(cast call "$PAR" 'getAddress(bytes32)(address)' \
  "$(cast keccak PRODUCT_REGISTRY)" --rpc-url "$RPC")

export PRODUCT_ID=$(cast keccak mainnet-rpc-10m-credits)

# 500 is commissionBps — 5% of a 10000 denominator. The uint8 after it is
# productType: 0 is the Repeat member, 1 is OneOff.
cast send "$PRODUCT_REGISTRY" 'addProduct(uint256,bytes32,uint16,uint8,string)' \
  "$MERCHANT_ID" "$PRODUCT_ID" 500 0 'ipfs://bafy…' \
  --rpc-url "$RPC" --private-key "$MERCHANT_KEY"

curl -X POST https://api.opensouk.ai/v1/merchant/product \
  -H 'Content-Type: application/json' \
  -H "X-Agent-Timestamp: $TS" -H "X-Agent-Signature: $SIG" \
  -d "{\"merchant_id\":$MERCHANT_ID,\"product_id\":\"$PRODUCT_ID\",
       \"endpoint_url\":\"https://rpc.example.com/v1/mainnet\",
       \"name\":\"Mainnet RPC, 10M credits\",
       \"description\":\"Archive-node RPC with a 50ms p95 target.\",
       \"category\":\"RPC Provider\"}"

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

Verify

The read needs no signature.

curl -G https://api.opensouk.ai/v1/merchant/product \
  --data-urlencode "merchant_id=$MERCHANT_ID" \
  --data-urlencode "product_id=$PRODUCT_ID"

{
  "merchant_id": 42,
  "product_id": "0x…",
  "commission_bps": 500,
  "cashback_bps": 0,
  "active": true,
  "product_card_uri": "ipfs://bafy…",
  "name": "Mainnet RPC, 10M credits",
  "description": "Archive-node RPC with a 50ms p95 target.",
  "category": "RPC Provider",
  "created_at": "2026-06-14T09:12:03Z",
  "product_type": "Repeat",
  "product_rank": 0.5
}

Three fields read differently than they look:

• cashback_bps is always 0. A retired field kept for response compatibility, not your rate and not anybody's.
• product_type is a string — Repeat or OneOff — not the uint8 you passed.
• An inactive product is a 404 here, hidden rather than reported. So a 404 immediately after a successful addProduct means our indexer has not caught up yet; retry rather than re-listing, because a second addProduct with the same id reverts.

If you are the first merchant on a fresh deployment, one asymmetry applies: identity ids start at zero, and this read rejects any merchant_id at or below zero with 400 invalid merchant_id while both registration routes accept zero. A merchant holding id 0 completes every step above and then cannot use this check.

Errors and retries

On-chain:

From the API:

Search relevance arrives after the response. The route computes an embedding for the product's name, description and category in the background, best-effort. A failure there is logged and ignored, so a 201 does not guarantee the product is semantically searchable yet — and repeating the metadata call recomputes it.

Next steps

• Accept agent payments over x402 — wiring the endpoint_url you just registered
• Merchant routes — both routes above, field by field
• Registries — addProduct, setProductActive and setProductCardURI, signature by signature