# Marketplace

This documentation covers the various endpoints and actions available for the Marketplace API. The API allows for operations such as creating, updating, deleting, and buying offers on the marketplace, as well as handling user sessions and royalty calculations.

**Base URL**

```
https://api.idosgames.com/api/[titleTemplateId]/[titleId]/Client/Marketplace/  
```

## CreateOffer

**Purpose:** To create a new offer on the marketplace.

**URL:**

```
https://api.idosgames.com/api/[titleTemplateId]/[titleId]/Client/Marketplace/CreateOffer  
```

**Method:** POST

**Request Parameters (JSON body):**

* `ItemID` (string): The ID of the item.
* `VirtualCurrencyID` (string): The ID of the virtual currency.
* `Price` (string): The price of the item.

**Responses:**

* `200 OK`: Operation successful. Returns a success message.
* `400 Bad Request`: Incorrect request parameters. Possible messages: "INVALID\_INPUT\_DATA", "ITEM\_NOT\_EXISTS\_IN\_INVENTORY", "INCORRECT\_VIRTUAL\_CURRENCY\_ID", "FAILED\_TO\_SAVE\_TO\_DATABASE", etc.

**Example Usage:**

**Request:**

```javascript
fetch('https://api.idosgames.com/api/[titleTemplateId]/[titleId]/Client/Marketplace/CreateOffer', {  
    method: 'POST',  
    headers: {  
        'Content-Type': 'application/json'  
    },  
    body: JSON.stringify({  
        ItemID: 'item-id-example',  
        VirtualCurrencyID: 'currency-id-example',  
        Price: '100'  
    })  
})  
.then(response => response.json())  
.then(data => console.log(data))  
.catch(error => console.error('Error:', error));  
```

**Response:**

```json
{  
    "Message": "SUCCESS"  
}  
```

## DeleteOffer

**Purpose:** To delete an offer from the marketplace.

**URL:**

```
https://api.idosgames.com/api/[titleTemplateId]/[titleId]/Client/Marketplace/DeleteOffer  
```

**Method:** POST

**Request Parameters (JSON body):**

* `ID` (string): The ID of the offer to delete.

**Responses:**

* `200 OK`: Operation successful. Returns a success message.
* `400 Bad Request`: Incorrect request parameters. Possible messages: "INVALID\_INPUT\_DATA", "ITEM\_NOT\_EXISTS\_IN\_DB", "ITEM\_OWNED\_BY\_ANOTHER\_USER", "FAILED\_TO\_UPDATE\_ITEM\_IN\_DB", etc.

**Example Usage:**

**Request:**

```javascript
fetch('https://api.idosgames.com/api/[titleTemplateId]/[titleId]/Client/Marketplace/DeleteOffer', {  
    method: 'POST',  
    headers: {  
        'Content-Type': 'application/json'  
    },  
    body: JSON.stringify({  
        ID: 'offer-id-example'  
    })  
})  
.then(response => response.json())  
.then(data => console.log(data))  
.catch(error => console.error('Error:', error));  
```

**Response:**

```json
{  
    "Message": "SUCCESS"  
}  
```

## UpdateOffer

**Purpose:** To update an existing offer on the marketplace.

**URL:**

```
https://api.idosgames.com/api/[titleTemplateId]/[titleId]/Client/Marketplace/UpdateOffer  
```

**Method:** POST

**Request Parameters (JSON body):**

* `ID` (string): The ID of the offer to update.
* `VirtualCurrencyID` (string): The new virtual currency ID.
* `Price` (string): The new price for the item.

**Responses:**

* `200 OK`: Operation successful. Returns a success message.
* `400 Bad Request`: Incorrect request parameters. Possible messages: "INVALID\_INPUT\_DATA", "ITEM\_NOT\_EXISTS\_IN\_DB", "ITEM\_OWNED\_BY\_ANOTHER\_USER", "NOTHING\_TO\_UPDATE", "FAILED\_TO\_UPDATE\_ITEM\_IN\_DB", etc.

**Example Usage:**

**Request:**

```javascript
fetch('https://api.idosgames.com/api/[titleTemplateId]/[titleId]/Client/Marketplace/UpdateOffer', {  
    method: 'POST',  
    headers: {  
        'Content-Type': 'application/json'  
    },  
    body: JSON.stringify({  
        ID: 'offer-id-example',  
        VirtualCurrencyID: 'new-currency-id',  
        Price: '150'  
    })  
})  
.then(response => response.json())  
.then(data => console.log(data))  
.catch(error => console.error('Error:', error));  
```

**Response:**

```json
{  
    "Message": "SUCCESS"  
}  
```

## BuyOffer

**Purpose:** To buy an offer on the marketplace.

**URL:**

```
https://api.idosgames.com/api/[titleTemplateId]/[titleId]/Client/Marketplace/BuyOffer  
```

**Method:** POST

**Request Parameters (JSON body):**

* `ID` (string): The ID of the offer to buy.

**Responses:**

* `200 OK`: Successful operation. Returns a success message.
* `400 Bad Request`: Incorrect request parameters or error in the buying process. Possible messages: "INVALID\_INPUT\_DATA", "ITEM\_NOT\_EXISTS\_IN\_DB", "CANT\_BUY\_YOUR\_ITEM", "NOT\_ENOUGH\_FUNDS", "FAILED\_TO\_MODIFY\_VIRTUAL\_CURRENCY", "FAILED\_TO\_GRANT\_ITEMS", "FAILED\_TO\_UPDATE\_ITEM\_IN\_DB", etc.

**Example Usage:**

**Request:**

```javascript
fetch('https://api.idosgames.com/api/[titleTemplateId]/[titleId]/Client/Marketplace/BuyOffer', {  
    method: 'POST',  
    headers: {  
        'Content-Type': 'application/json'  
    },  
    body: JSON.stringify({  
        ID: 'offer-id-example'  
    })  
})  
.then(response => response.json())  
.then(data => console.log(data))  
.catch(error => console.error('Error:', error));  
```

**Response:**

```json
{  
    "Message": "SUCCESS"  
}  
```

***

## **GetGroupedActiveOffers**

Retrieves grouped active offers for the specified title.

**Action**: `GroupedOffers`

**Purpose**: Retrieves grouped active offers based on ItemID.

**Example Usage**

Request:

```javascript
fetch('https://api.example.com/api/1234/5678/Client/MarketplaceData/GroupedOffers', {    
    method: 'POST',    
    headers: {    
        'Content-Type': 'application/json'    
    },    
    body: JSON.stringify({    
        WebAppLink: 'https://example.com',  
        UserID: 'example-user-id',    
        ClientSessionTicket: 'valid-session-ticket',    
        EntityToken: 'example-token',    
        UsageTime: 120  
    })    
})    
.then(response => response.json())    
.then(data => console.log(data))    
.catch(error => console.error('Error:', error));  
```

Response:

```json
{  
    "Items": [  
        {"ItemID": "item1", "OfferCount": 5},  
        {"ItemID": "item2", "OfferCount": 3}  
    ]  
}  
```

## **GetActiveOffersByItemID**

Retrieves active offers for a specific item ID.

**Action**: `ActiveOffersByItemID`

**Purpose**: Retrieves active offers based on ItemID, with optional filtering and sorting.

**Example Usage**

Request:

```javascript
fetch('https://api.example.com/api/1234/5678/Client/MarketplaceData/ActiveOffersByItemID', {    
    method: 'POST',    
    headers: {    
        'Content-Type': 'application/json'    
    },    
    body: JSON.stringify({    
        ItemID: 'example-item-id',    
        VirtualCurrencyID: 'USD',  
        PriceFrom: '1.00',  
        PriceTo: '10.00',  
        SortOrder: 'Ascending',    
        OrderBy: 'Price',    
        MaxItemCount: 10  
    })    
})    
.then(response => response.json())    
.then(data => console.log(data))    
.catch(error => console.error('Error:', error));  
```

Response:

```json
{  
    "Items": [  
        {"ID": "offer1", "ItemID": "example-item-id", "SellerID": "seller1", "CurrencyID": "USD", "Price": 5.00},  
        {"ID": "offer2", "ItemID": "example-item-id", "SellerID": "seller2", "CurrencyID": "USD", "Price": 8.00}  
    ],  
    "ContinuationToken": "next-token-id"  
}  
```

## **GetPlayerHistory**

Retrieves player transaction history.

**Action**: `PlayerHistory`

**Purpose**: Retrieves the transaction history for a player based on their UserID.

**Example Usage**

Request:

```javascript
fetch('https://api.example.com/api/1234/5678/Client/MarketplaceData/PlayerHistory', {    
    method: 'POST',    
    headers: {    
        'Content-Type': 'application/json'    
    },    
    body: JSON.stringify({    
        UserID: 'example-user-id',    
        MaxItemCount: 10    
    })    
})    
.then(response => response.json())    
.then(data => console.log(data))    
.catch(error => console.error('Error:', error));  
```

Response:

```json
{  
    "Items": [  
        {"ID": "history1", "ItemID": "item1", "SellerID": "seller1", "BuyerID": "example-user-id", "CurrencyID": "USD", "Price": 10.00},  
        {"ID": "history2", "ItemID": "item2", "SellerID": "seller2", "BuyerID": "example-user-id", "CurrencyID": "USD", "Price": 15.00}  
    ],  
    "ContinuationToken": "next-token-id"  
}  
```

## **GetPlayerActiveOffers**

Retrieves active offers by a player.

**Action**: `PlayerActiveOffers`

**Purpose**: Retrieves the active offers for a player based on their UserID.

**Example Usage**

Request:

```javascript
fetch('https://api.example.com/api/1234/5678/Client/MarketplaceData/PlayerActiveOffers', {    
    method: 'POST',    
    headers: {    
        'Content-Type': 'application/json'    
    },    
    body: JSON.stringify({    
        UserID: 'example-user-id',    
        MaxItemCount: 10    
    })    
})    
.then(response => response.json())    
.then(data => console.log(data))    
.catch(error => console.error('Error:', error));  
```

Response:

```json
{  
    "Items": [  
        {"ID": "offer1", "ItemID": "item1", "SellerID": "example-user-id", "CurrencyID": "USD", "Price": 10.00},  
        {"ID": "offer2", "ItemID": "item2", "SellerID": "example-user-id", "CurrencyID": "USD", "Price": 15.00}  
    ],  
    "ContinuationToken": "next-token-id"  
}  
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.idosgames.com/api/api-v1/marketplace.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.