subcent

Merchants API

Merchants are businesses or services that receive payments from AI agents through Subcent. Each merchant has a wallet address, a business category, and an optional product catalog.

Register Merchant#

POST
/v1/merchants/register

Register a new merchant to receive agent payments.

Request Body#

| Field | Type | Required | Description | |---|---|---|---| | wallet_address | string | Yes | The merchant's wallet address for receiving payments | | chain | string | Yes | Blockchain the merchant operates on: "solana" or "base" | | business_name | string | Yes | Display name of the business | | category | string | Yes | Business category (e.g., "groceries", "electronics", "api_services") | | catalog_url | string | No | URL to the merchant's product catalog API | | webhook_url | string | No | URL to receive payment notifications |

Standard Categories#

Merchants should use one of the standard categories for policy compatibility:

groceries, household, electronics, clothing, health, beauty, books, entertainment, api_services, data_services, computing, storage, transportation, food_delivery, subscription

Example Request#

{
  "wallet_address": "8xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "chain": "solana",
  "business_name": "FreshMart Groceries",
  "category": "groceries",
  "catalog_url": "https://api.freshmart.com/catalog",
  "webhook_url": "https://api.freshmart.com/subcent/webhooks"
}

Response#

{
  "merchant_id": "mrc_660e8400-e29b-41d4-a716-446655440000",
  "wallet_address": "8xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "business_name": "FreshMart Groceries",
  "category": "groceries",
  "status": "pending_verification",
  "created_at": "2025-01-15T10:30:00.000Z"
}
i

Newly registered merchants start in pending_verification status. Verification is completed after confirming wallet ownership. Agents can still target pending_verification merchants for payment requests.

Errors#

| Error Code | Description | |---|---| | internal_error | Unexpected server error |

Get Merchant Catalog#

GET
/v1/merchants/:id/catalog

Retrieve merchant catalog information.

This endpoint returns merchant details along with their product catalog. If the merchant has synced a catalog, items will be included in the response.

Path Parameters#

| Parameter | Type | Description | |---|---|---| | id | string | The merchant ID |

Response#

{
  "merchant_id": "mrc_660e8400-e29b-41d4-a716-446655440000",
  "items": [
    {
      "itemId": "item_001",
      "name": "Organic Bananas",
      "description": "Fresh organic bananas, 1 bunch",
      "price": "3.99",
      "currency": "USDC",
      "category": "groceries",
      "inStock": true,
      "stockQuantity": 150,
      "deliveryDays": 1,
      "deliveryFee": "0.00",
      "rating": 4.8,
      "reviewCount": 234
    }
  ],
  "total_items": 1,
  "last_updated": "2025-01-15T10:30:00.000Z"
}

Errors#

| Error Code | Description | |---|---| | merchant_not_found | No merchant exists with the given ID |

Merchant Statuses#

| Status | Description | |---|---| | pending_verification | Merchant is registered but wallet ownership not yet verified | | verified | Merchant is fully verified and operational | | suspended | Merchant account is suspended; payments will be rejected |