# MarketPlace

## Marketplace API

Interact with the REALM AI decentralized marketplace built on Solana. List, discover, and acquire AI models and influencers.

### Base URL

`https://api.realm.ai/v1/marketplace`

### Solana Integration

Marketplace operations (listing, buying) involve interactions with the Solana blockchain. Responses may include transaction details or require wallet signatures. See the Solana Integration section for more details.

***

#### List Item for Sale

Creates a listing on the marketplace for a specific AI model or influencer.

* **Method:** `POST`
* **Endpoint:** `/listings`
* **Authentication:** API Key + Signature Authentication

**Request Body**

```json
{
  "assetType": "model", // or "influencer"
  "assetId": "mod_zyx987", // ID of the model or influencer profile
  "price": 15.75, // Price in SOL
  "currency": "SOL",
  "description": "Highly trained cyberpunk model, photorealistic.",
  "listingType": "fixed_price" // Could also be "auction"
}
```

**Response `201 Created`**

```json
{
  "listingId": "list_abc123",
  "assetType": "model",
  "assetId": "mod_zyx987",
  "sellerWallet": "YourSoLAnAaDdReSs...",
  "price": 15.75,
  "currency": "SOL",
  "status": "active", // e.g., active, sold, cancelled
  "createdAt": "2024-03-10T17:00:00Z",
  "solanaTxSignature": "SolTxSigIfNeeded..." // May be included if listing creation requires on-chain action
}
```

***

#### Get Listing Details

Retrieves details for a specific marketplace listing.

* **Method:** `GET`
* **Endpoint:** `/listings/{listingId}`
* **Authentication:** API Key

**Response `200 OK`**

```json
{
  "listingId": "list_abc123",
  "assetType": "model",
  "assetId": "mod_zyx987",
  "assetDetails": { // Include relevant details of the listed asset
      "name": "My Custom Model",
      "description": "A model specialized for cyberpunk aesthetics",
      "tags": ["cyberpunk", "female", "photorealistic"],
      "previewImageUrl": "https://cdn.realm.ai/previews/mod_zyx987.jpg"
  },
  "sellerWallet": "SellerSoLAnAaDdReSs...",
  "price": 15.75,
  "currency": "SOL",
  "status": "active",
  "createdAt": "2024-03-10T17:00:00Z"
}
```

***

#### Search Listings

Searches for active listings based on various criteria.

* **Method:** `GET`
* **Endpoint:** `/listings/search`
* **Authentication:** API Key
* **Query Parameters:**
  * `query` (string, optional): Keyword search in name/description.
  * `assetType` (string, optional): Filter by `model` or `influencer`.
  * `tags` (string, optional): Comma-separated tags.
  * `minPrice` (float, optional).
  * `maxPrice` (float, optional).
  * `sortBy` (string, optional, default: `createdAt`): e.g., `price`, `createdAt`.
  * `sortOrder` (string, optional, default: `desc`): `asc` or `desc`.
  * `limit` (int, optional, default: 20).
  * `offset` (int, optional, default: 0).

**Response `200 OK`**

```json
{
  "data": [
    // Array of listing objects (similar structure to Get Listing Details)
    {
      "listingId": "list_abc123",
      "assetType": "model",
      "assetId": "mod_zyx987",
      "assetDetails": { "name": "My Custom Model", ... },
      "price": 15.75,
      "currency": "SOL",
      "status": "active",
      "createdAt": "2024-03-10T17:00:00Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 1 // Total matching listings
  }
}
```

***

#### Initiate Purchase

Initiates the purchase process for a listed item. This typically involves preparing a Solana transaction for the user to sign.

* **Method:** `POST`
* **Endpoint:** `/listings/{listingId}/purchase`
* **Authentication:** API Key + Signature Authentication

**Response `200 OK`**

```json
{
  "listingId": "list_abc123",
  "buyerWallet": "YourSoLAnAaDdReSs...",
  "price": 15.75,
  "currency": "SOL",
  "status": "pending_signature",
  "solanaTransaction": "base64_encoded_unsigned_solana_transaction...", // User needs to sign this
  "expiresAt": "2024-03-10T18:05:00Z" // Time limit to sign the transaction
}
```

*(Note: A subsequent endpoint might be needed to confirm the purchase after the transaction is signed and broadcasted, or this might be handled via webhooks/polling Solana.)*

***

#### Cancel Listing

Cancels an active listing owned by the authenticated user.

* **Method:** `DELETE`
* **Endpoint:** `/listings/{listingId}`
* **Authentication:** API Key + Signature Authentication

**Response `204 No Content`**