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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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