### Install MarvelRivalsAPI Wrapper

Source: https://github.com/marvelrivalsapi/marvelrivalsapi-wrapper/blob/main/README.md

Install the official Node.js wrapper for MarvelRivalsAPI.com using npm.

```bash
npm install marvelrivalsapi
```

--------------------------------

### Install and Initialize Marvel Rivals API Wrapper

Source: https://context7.com/marvelrivalsapi/marvelrivalsapi-wrapper/llms.txt

Install the package using npm and initialize the API instance with your unique API key. The API instance provides access to various endpoints for different data categories.

```javascript
// Install the package
// npm install marvelrivalsapi

const MarvelRivals = require("marvelrivalsapi");

// Initialize the API with your key
const API = new MarvelRivals.API("YOUR_API_KEY");

// The API instance provides access to all endpoints:
// API.player       - Player stats (v1)
// API.playerv2     - Player stats (v2)
// API.heroes       - Heroes data (v1)
// API.heroesv2     - Heroes data (v2)
// API.matchhistory - Match history (v2)
// API.matchhistoryv1 - Match history (v1)
// API.match        - Match details
// API.achievements - Achievements
// API.balances     - Balance changes
// API.battlepass   - Battle pass data
// API.devdiary     - Developer diaries
// API.items        - Cosmetic items
// API.maps         - Map listings (v1)
// API.map          - Map details (v2)
// API.patchnotes   - Patch notes
```

--------------------------------

### GET /balances

Source: https://context7.com/marvelrivalsapi/marvelrivalsapi-wrapper/llms.txt

Retrieve hero balance change history and patch-specific adjustments.

```APIDOC
## GET /balances

### Description
Retrieve a paginated list of hero balance changes or details for a specific balance adjustment.

### Method
GET

### Endpoint
/balances

### Query Parameters
- **page** (integer) - Optional - Page number for pagination
- **limit** (integer) - Optional - Number of items per page

### Response
#### Success Response (200)
- **balances** (array) - List of balance change records
- **total** (integer) - Total count of records
- **page** (integer) - Current page number

#### Response Example
{
  "balances": [{"id": "balance_123", "date": "2023-10-01", "changes": []}],
  "total": 1,
  "page": 1
}
```

--------------------------------

### Get All Balance Changes

Source: https://context7.com/marvelrivalsapi/marvelrivalsapi-wrapper/llms.txt

Retrieve a paginated list of all hero balance changes. Requires an API key for initialization.

```javascript
const MarvelRivals = require("marvelrivalsapi");
const API = new MarvelRivals.API("YOUR_API_KEY");

// Get all balance changes with pagination
async function getAllBalances() {
    try {
        const balances = await API.balances.getAllBalances({
            page: 1,
            limit: 10
        });
        console.log(balances);
        // Returns: { balances: [{ id, date, changes: [...] }], total, page }
    } catch (error) {
        console.error("Error:", error.message);
    }
}

getAllBalances();
```

--------------------------------

### GET /items

Source: https://context7.com/marvelrivalsapi/marvelrivalsapi-wrapper/llms.txt

Access cosmetic items including emotes, MVPs, nameplates, and sprays.

```APIDOC
## GET /items

### Description
Retrieve a list of cosmetic items with optional filtering by type.

### Method
GET

### Endpoint
/items

### Query Parameters
- **type** (string) - Optional - Filter by "emote", "mvp", "nameplate", or "spray"
- **page** (integer) - Optional - Page number
- **limit** (integer) - Optional - Items per page

### Response
#### Success Response (200)
- **items** (array) - List of items
- **total** (integer) - Total count
- **page** (integer) - Current page

#### Response Example
{
  "items": [{"id": "victory_dance", "name": "Victory Dance", "type": "emote"}],
  "total": 1,
  "page": 1
}
```

--------------------------------

### Get All Items with Filters

Source: https://context7.com/marvelrivalsapi/marvelrivalsapi-wrapper/llms.txt

Retrieve a paginated list of all cosmetic items, with options to filter by item type. Requires an API key.

```javascript
const MarvelRivals = require("marvelrivalsapi");
const API = new MarvelRivals.API("YOUR_API_KEY");

// Get all items with filters
async function getAllItems() {
    try {
        // Get all items
        const allItems = await API.items.getAllItems({
            page: 1,
            limit: 20
        });
        console.log(allItems);

        // Filter by item type
        const emotes = await API.items.getAllItems({
            type: "emote",  // Options: "emote", "mvp", "nameplate", "spray"
            page: 1,
            limit: 10
        });
        console.log(emotes);
        // Returns: { items: [{ id, name, type, rarity, ... }], total, page }
    } catch (error) {
        console.error("Error:", error.message);
    }
}

getAllItems();
```

--------------------------------

### Get All Dev Diaries

Source: https://context7.com/marvelrivalsapi/marvelrivalsapi-wrapper/llms.txt

Retrieve a paginated list of all developer diary entries. Requires an API key for initialization.

```javascript
const MarvelRivals = require("marvelrivalsapi");
const API = new MarvelRivals.API("YOUR_API_KEY");

// Get all dev diaries with pagination
async function getAllDevDiaries() {
    try {
        const diaries = await API.devdiary.getAllDevDiaries({
            page: 1,
            limit: 10
        });
        console.log(diaries);
        // Returns: { devDiaries: [{ id, title, date, videoUrl, ... }], total, page }
    } catch (error) {
        console.error("Error:", error.message);
    }
}

getAllDevDiaries();
```

--------------------------------

### GET /devdiaries

Source: https://context7.com/marvelrivalsapi/marvelrivalsapi-wrapper/llms.txt

Access developer diary content including videos and announcements.

```APIDOC
## GET /devdiaries

### Description
Retrieve a list of developer diaries or details for a specific diary entry.

### Method
GET

### Endpoint
/devdiaries

### Query Parameters
- **page** (integer) - Optional - Page number
- **limit** (integer) - Optional - Items per page

### Response
#### Success Response (200)
- **devDiaries** (array) - List of diary entries
- **total** (integer) - Total count
- **page** (integer) - Current page

#### Response Example
{
  "devDiaries": [{"id": "diary_123", "title": "Update News", "date": "2023-10-01"}],
  "total": 1,
  "page": 1
}
```

--------------------------------

### GET /battlepass

Source: https://context7.com/marvelrivalsapi/marvelrivalsapi-wrapper/llms.txt

Access battle pass data including rewards and progression tiers for different seasons.

```APIDOC
## GET /battlepass

### Description
Retrieve battle pass information for the current or a specific season.

### Method
GET

### Endpoint
/battlepass

### Query Parameters
- **season** (integer) - Optional - The season number to retrieve

### Response
#### Success Response (200)
- **season** (integer) - Season identifier
- **tiers** (array) - List of progression tiers and rewards

#### Response Example
{
  "season": 2,
  "tiers": [{"level": 1, "freeReward": "item_id", "premiumReward": "item_id"}]
}
```

--------------------------------

### Get Specific Item by ID or Name

Source: https://context7.com/marvelrivalsapi/marvelrivalsapi-wrapper/llms.txt

Fetch details for a specific cosmetic item using its ID or name. Ensure the correct identifier is provided.

```javascript
const MarvelRivals = require("marvelrivalsapi");
const API = new MarvelRivals.API("YOUR_API_KEY");

// Get specific item by ID or name
async function getItem() {
    try {
        const item = await API.items.getItem("victory_dance");
        console.log(item);
        // Returns: { id, name, type, rarity, description, imageUrl, ... }
    } catch (error) {
        console.error("Item not found:", error.message);
    }
}

getItem();
```

--------------------------------

### Get Match Details

Source: https://context7.com/marvelrivalsapi/marvelrivalsapi-wrapper/llms.txt

Retrieve detailed information for a specific match using its unique match ID. Requires API key initialization.

```javascript
const MarvelRivals = require("marvelrivalsapi");
const API = new MarvelRivals.API("YOUR_API_KEY");

// Get detailed match information
async function getMatchDetails() {
    try {
        const matchDetails = await API.match.getMatchDetails("match_uid_12345");
        console.log(matchDetails);
    } catch (error) {
        console.error("Match not found:", error.message);
    }
}

getMatchDetails();
```

--------------------------------

### Get All Maps

Source: https://context7.com/marvelrivalsapi/marvelrivalsapi-wrapper/llms.txt

Retrieve a paginated list of all available maps using the v1 endpoint. Requires an API key for initialization.

```javascript
const MarvelRivals = require("marvelrivalsapi");
const API = new MarvelRivals.API("YOUR_API_KEY");

// Get all maps (v1 endpoint)
async function getAllMaps() {
    try {
        const maps = await API.maps.getAllMaps({
            page: 1,
            limit: 10
        });
        console.log(maps);
        // Returns: { maps: [{ id, name, gameMode, ... }], total, page }
    } catch (error) {
        console.error("Error:", error.message);
    }
}

getAllMaps();
```

--------------------------------

### Get Player Match History (v1)

Source: https://context7.com/marvelrivalsapi/marvelrivalsapi-wrapper/llms.txt

Retrieve player match history using the v1 endpoint. This version offers similar functionality to v2 but with the original API format. Requires API key initialization.

```javascript
const MarvelRivals = require("marvelrivalsapi");
const API = new MarvelRivals.API("YOUR_API_KEY");

// Get match history using v1 endpoint
async function getMatchHistoryV1() {
    try {
        const history = await API.matchhistoryv1.findPlayerMatchHistory("PlayerName", {
            season: 1,
            skip: 20,
            game_mode: 0,
            timestamp: 1704067200
        });

        console.log(history);
    } catch (error) {
        console.error("Error:", error.message);
    }
}

getMatchHistoryV1();
```

--------------------------------

### GET /maps

Source: https://context7.com/marvelrivalsapi/marvelrivalsapi-wrapper/llms.txt

Access map data including listings and individual map details.

```APIDOC
## GET /maps

### Description
Retrieve a list of maps or details for a specific map.

### Method
GET

### Endpoint
/maps

### Query Parameters
- **page** (integer) - Optional - Page number
- **limit** (integer) - Optional - Items per page

### Response
#### Success Response (200)
- **maps** (array) - List of maps
- **total** (integer) - Total count
- **page** (integer) - Current page

#### Response Example
{
  "maps": [{"id": "tokyo_2099", "name": "Tokyo 2099", "gameMode": "Control"}],
  "total": 1,
  "page": 1
}
```

--------------------------------

### Get Player Match History (v2)

Source: https://context7.com/marvelrivalsapi/marvelrivalsapi-wrapper/llms.txt

Retrieve a player's match history with comprehensive filtering options including season, pagination, game mode, and timestamp filters. Requires API key initialization.

```javascript
const MarvelRivals = require("marvelrivalsapi");
const API = new MarvelRivals.API("YOUR_API_KEY");

// Get player match history with filters
async function getMatchHistory() {
    try {
        // Basic match history
        const history = await API.matchhistory.findPlayerMatchHistory("PlayerName");
        console.log(history);

        // With comprehensive filters
        const filteredHistory = await API.matchhistory.findPlayerMatchHistory("PlayerName", {
            season: 2,
            page: 1,
            limit: 40,
            skip: 0,
            game_mode: 0,
            timestamp: 1704067200
        });

        console.log(filteredHistory);
    } catch (error) {
        console.error("Error fetching match history:", error.message);
    }
}

getMatchHistory();
```

--------------------------------

### Get Battle Pass Data

Source: https://context7.com/marvelrivalsapi/marvelrivalsapi-wrapper/llms.txt

Fetch battle pass information for the current season or a specific season. Requires an API key.

```javascript
const MarvelRivals = require("marvelrivalsapi");
const API = new MarvelRivals.API("YOUR_API_KEY");

// Get battle pass data
async function getBattlepass() {
    try {
        // Get current season battle pass
        const currentBattlepass = await API.battlepass.getBattlepass();
        console.log(currentBattlepass);

        // Get specific season battle pass
        const season2Battlepass = await API.battlepass.getBattlepass({
            season: 2
        });
        console.log(season2Battlepass);
        // Returns: { season, tiers: [{ level, freeReward, premiumReward, ... }], ... }
    } catch (error) {
        console.error("Error:", error.message);
    }
}

getBattlepass();
```

--------------------------------

### Get Specific Balance Change by ID

Source: https://context7.com/marvelrivalsapi/marvelrivalsapi-wrapper/llms.txt

Retrieve details for a specific hero balance change using its unique ID. Ensure the correct ID is provided.

```javascript
const MarvelRivals = require("marvelrivalsapi");
const API = new MarvelRivals.API("YOUR_API_KEY");

// Get specific balance change by ID
async function getBalance() {
    try {
        const balance = await API.balances.getBalance("balance_123");
        console.log(balance);
        // Returns: { id, patchVersion, date, heroChanges: [...] }
    } catch (error) {
        console.error("Balance not found:", error.message);
    }
}

getBalance();
```

--------------------------------

### Get Specific Dev Diary

Source: https://context7.com/marvelrivalsapi/marvelrivalsapi-wrapper/llms.txt

Fetch a specific developer diary entry using its unique ID. Ensure the correct ID is provided.

```javascript
const MarvelRivals = require("marvelrivalsapi");
const API = new MarvelRivals.API("YOUR_API_KEY");

// Get specific dev diary
async function getDevDiary() {
    try {
        const diary = await API.devdiary.getDevDiary("diary_123");
        console.log(diary);
        // Returns: { id, title, description, date, content, ... }
    } catch (error) {
        console.error("Dev diary not found:", error.message);
    }
}

getDevDiary();
```

--------------------------------

### Get Player Statistics (v2)

Source: https://context7.com/marvelrivalsapi/marvelrivalsapi-wrapper/llms.txt

Fetch player statistics using the v2 endpoint, allowing for specific season data retrieval. This function returns comprehensive stats including rank, matches played, and win rate. Error handling is crucial.

```javascript
const MarvelRivals = require("marvelrivalsapi");
const API = new MarvelRivals.API("YOUR_API_KEY");

// Get player stats with v2 endpoint and filters
async function getPlayerStatsV2() {
    try {
        // Retrieve stats for a specific season
        const stats = await API.playerv2.getPlayerStats("PlayerName", {
            season: 2
        });
        console.log(stats);
        // Returns: { uid, username, rank, matchesPlayed, winRate, heroPerformance: [...], ... }
    } catch (error) {
        console.error("Error:", error.message);
    }
}

getPlayerStatsV2();
```

--------------------------------

### Get Player Statistics (v1)

Source: https://context7.com/marvelrivalsapi/marvelrivalsapi-wrapper/llms.txt

Retrieve detailed player statistics, optionally filtering by season. This function returns rank, wins, losses, and hero-specific performance data. Handle potential errors during data retrieval.

```javascript
const MarvelRivals = require("marvelrivalsapi");
const API = new MarvelRivals.API("YOUR_API_KEY");

// Get detailed player statistics with optional filters
async function getPlayerStats() {
    try {
        // Basic stats retrieval
        const stats = await API.player.getPlayerStats("PlayerName");
        console.log(stats);

        // With season filter
        const seasonStats = await API.player.getPlayerStats("PlayerName", { season: 2 });
        console.log(seasonStats);
        // Returns: { username, rank, wins, losses, heroStats: [...], ... }
    } catch (error) {
        console.error("Error fetching stats:", error.message);
    }
}

getPlayerStats();
```

--------------------------------

### Get Specific Map Details

Source: https://context7.com/marvelrivalsapi/marvelrivalsapi-wrapper/llms.txt

Fetch detailed information for a specific map using its identifier via the v2 endpoint. Ensure the correct map ID is provided.

```javascript
const MarvelRivals = require("marvelrivalsapi");
const API = new MarvelRivals.API("YOUR_API_KEY");

// Get specific map details (v2 endpoint)
async function getMap() {
    try {
        const map = await API.map.getMap("tokyo_2099");
        console.log(map);
        // Returns: { id, name, description, gameMode, imageUrl, objectives, ... }
    } catch (error) {
        console.error("Map not found:", error.message);
    }
}

getMap();
```

--------------------------------

### Initialize API and Fetch Data

Source: https://github.com/marvelrivalsapi/marvelrivalsapi-wrapper/blob/main/README.md

Initialize the MarvelRivalsAPI wrapper with your API key and demonstrate fetching match details, player stats, and hero costume information using async/await syntax.

```javascript
const MarvelRivals = require("marvelrivalsapi");
const API = new MarvelRivals.API("YOUR_API_KEY");

API.matchStats.getMatchDetails("match_id").then((res) => {
    console.log(res); // Fetches match details by match ID
});

API.playerStats.getPlayerStats("player_name").then((res) => {
    console.log(res); // Fetches player stats by username
});

API.heroes.getHeroCostume("hero_name", "costume_id").then((res) => {
    console.log(res); // Fetches hero details and specific costume details
});
```

--------------------------------

### Retrieve Patch Notes with JavaScript

Source: https://context7.com/marvelrivalsapi/marvelrivalsapi-wrapper/llms.txt

Fetch all patch notes with pagination or retrieve a specific version by its identifier.

```javascript
const MarvelRivals = require("marvelrivalsapi");
const API = new MarvelRivals.API("YOUR_API_KEY");

// Get all patch notes with pagination
async function getAllPatchNotes() {
    try {
        const patchNotes = await API.patchnotes.getAllPatchNotes({
            page: 1,
            limit: 10
        });
        console.log(patchNotes);
        // Returns: { patchNotes: [{ id, version, date, title, ... }], total, page }
    } catch (error) {
        console.error("Error:", error.message);
    }
}

// Get specific patch note
async function getPatchNote() {
    try {
        const patchNote = await API.patchnotes.getPatchNote("1.2.0");
        console.log(patchNote);
        // Returns: { id, version, date, title, content, changes: [...] }
    } catch (error) {
        console.error("Patch note not found:", error.message);
    }
}

getAllPatchNotes();
getPatchNote();
```

--------------------------------

### Implement Error Handling with JavaScript

Source: https://context7.com/marvelrivalsapi/marvelrivalsapi-wrapper/llms.txt

Handle validation, API response, and network errors when interacting with the wrapper. Use Promise.all for efficient parallel data fetching.

```javascript
const MarvelRivals = require("marvelrivalsapi");
const API = new MarvelRivals.API("YOUR_API_KEY");

// Comprehensive error handling example
async function safeApiCall() {
    try {
        // This will throw if username is null/undefined
        const stats = await API.player.getPlayerStats(null);
    } catch (error) {
        if (error.message === "Username is required.") {
            console.error("Validation error: Please provide a username");
        } else if (error.response) {
            // API returned an error response
            console.error("API Error:", error.response.status, error.response.data);
        } else if (error.request) {
            // Network error
            console.error("Network error: Unable to reach API");
        } else {
            console.error("Unexpected error:", error.message);
        }
    }
}

// Wrapper function for safe API calls
async function fetchPlayerData(username) {
    if (!username || typeof username !== "string") {
        throw new Error("Valid username string is required");
    }

    try {
        const [profile, history] = await Promise.all([
            API.playerv2.getPlayerStats(username),
            API.matchhistory.findPlayerMatchHistory(username, { limit: 10 })
        ]);

        return { profile, history };
    } catch (error) {
        console.error(`Failed to fetch data for ${username}:`, error.message);
        return null;
    }
}

fetchPlayerData("PlayerName").then(data => {
    if (data) {
        console.log("Player Profile:", data.profile);
        console.log("Recent Matches:", data.history);
    }
});
```

--------------------------------

### Find Player by Username (v2)

Source: https://context7.com/marvelrivalsapi/marvelrivalsapi-wrapper/llms.txt

Utilize the v2 endpoint to find a player, which may return enhanced data fields compared to the v1 endpoint. This function is asynchronous and requires proper error handling.

```javascript
const MarvelRivals = require("marvelrivalsapi");
const API = new MarvelRivals.API("YOUR_API_KEY");

// Find a player using v2 endpoint
async function findPlayerV2() {
    try {
        const result = await API.playerv2.findPlayer("PlayerName");
        console.log(result);
        // Returns enhanced player data with v2 fields
    } catch (error) {
        console.error("Player not found:", error.message);
    }
}

findPlayerV2();
```

--------------------------------

### Find Player by Username (v1)

Source: https://context7.com/marvelrivalsapi/marvelrivalsapi-wrapper/llms.txt

Use this function to find a player by their username. It returns basic player information including UID, username, and level. Ensure the API key is valid and the player exists.

```javascript
const MarvelRivals = require("marvelrivalsapi");
const API = new MarvelRivals.API("YOUR_API_KEY");

// Find a player by username
async function findPlayer() {
    try {
        const result = await API.player.findPlayer("PlayerName");
        console.log(result);
        // Returns: { uid: "123456", username: "PlayerName", level: 45, ... }
    } catch (error) {
        console.error("Player not found:", error.message);
    }
}

findPlayer();
```

--------------------------------

### Access Hero Data (v1)

Source: https://context7.com/marvelrivalsapi/marvelrivalsapi-wrapper/llms.txt

Retrieve hero listings, details, stats, leaderboards, and costume information using the v1 API endpoints.

```javascript
const MarvelRivals = require("marvelrivalsapi");
const API = new MarvelRivals.API("YOUR_API_KEY");

// Get all heroes with pagination
async function getAllHeroes() {
    try {
        const heroes = await API.heroes.getAllHeroes({
            page: 1,
            limit: 10
        });
        console.log(heroes);
        // Returns: { heroes: [{ id, name, role, ... }], total, page }
    } catch (error) {
        console.error("Error:", error.message);
    }
}

// Get specific hero details
async function getHero() {
    try {
        const hero = await API.heroes.getHero("Iron Man");
        console.log(hero);
        // Returns: { id, name, role, abilities: [...], lore, ... }
    } catch (error) {
        console.error("Hero not found:", error.message);
    }
}

// Get hero statistics
async function getHeroStats() {
    try {
        const stats = await API.heroes.getHeroStats("Spider-Man");
        console.log(stats);
        // Returns: { pickRate, winRate, avgDamage, avgHealing, ... }
    } catch (error) {
        console.error("Error:", error.message);
    }
}

// Get hero leaderboard by platform
async function getHeroLeaderboard() {
    try {
        // PC leaderboard (default)
        const pcLeaderboard = await API.heroes.getHeroLeaderboard("Hulk");

        // PlayStation leaderboard
        const psLeaderboard = await API.heroes.getHeroLeaderboard("Hulk", {
            platform: "ps"  // Options: "pc", "ps", "xbox"
        });

        console.log(psLeaderboard);
        // Returns: { hero, platform, rankings: [{ rank, player, score, ... }] }
    } catch (error) {
        console.error("Error:", error.message);
    }
}

// Get all costumes for a hero
async function getHeroCostumes() {
    try {
        const costumes = await API.heroes.getHeroCostumes("Black Panther");
        console.log(costumes);
        // Returns: { hero, costumes: [{ id, name, rarity, ... }] }
    } catch (error) {
        console.error("Error:", error.message);
    }
}

// Get specific costume details
async function getHeroCostume() {
    try {
        const costume = await API.heroes.getHeroCostume("Iron Man", "Mark 85");
        console.log(costume);
        // Returns: { hero, costume: { id, name, rarity, imageUrl, ... } }
    } catch (error) {
        console.error("Costume not found:", error.message);
    }
}

getAllHeroes();
getHero();
getHeroStats();
getHeroLeaderboard();
getHeroCostumes();
getHeroCostume();
```

--------------------------------

### Match History (v2)

Source: https://context7.com/marvelrivalsapi/marvelrivalsapi-wrapper/llms.txt

Retrieve a player's match history with comprehensive filtering options including season, pagination, game mode, and timestamp filters.

```APIDOC
## Match History (v2)

### Description
Retrieve a player's match history with comprehensive filtering options including season, pagination, game mode, and timestamp filters.

### Method
GET

### Endpoint
/api/v2/matchhistory/{playerName}

### Parameters
#### Path Parameters
- **playerName** (string) - Required - The name of the player whose match history is to be retrieved.

#### Query Parameters
- **season** (integer) - Optional - Filter by season number.
- **page** (integer) - Optional - Page number for pagination (default: 1).
- **limit** (integer) - Optional - Number of matches per page (default: 40).
- **skip** (integer) - Optional - Number of matches to skip for pagination.
- **game_mode** (integer) - Optional - Filter by game mode ID.
- **timestamp** (integer) - Optional - Unix timestamp to filter matches occurring after this time.

### Request Example
```javascript
const MarvelRivals = require("marvelrivalsapi");
const API = new MarvelRivals.API("YOUR_API_KEY");

async function getMatchHistory() {
    try {
        const filteredHistory = await API.matchhistory.findPlayerMatchHistory("PlayerName", {
            season: 2,
            page: 1,
            limit: 40,
            skip: 0,
            game_mode: 0,
            timestamp: 1704067200
        });
        console.log(filteredHistory);
    } catch (error) {
        console.error("Error fetching match history:", error.message);
    }
}

getMatchHistory();
```

### Response
#### Success Response (200)
- **matches** (array) - An array of match objects.
- **totalMatches** (integer) - The total number of matches found.

#### Response Example
```json
{
  "matches": [
    {
      "matchId": "some_match_id",
      "date": "2024-01-15T20:30:00Z",
      "result": "win",
      "heroes": ["hero1", "hero2"],
      "performance": { "kills": 10, "deaths": 5, "assists": 8 }
    }
  ],
  "totalMatches": 150
}
```
```

--------------------------------

### Heroes (v1) API

Source: https://context7.com/marvelrivalsapi/marvelrivalsapi-wrapper/llms.txt

Access hero data including listings, individual hero details, stats, leaderboards, and costume information.

```APIDOC
## GET /heroes

### Description
Retrieves a paginated list of all heroes.

### Method
GET

### Endpoint
/heroes

### Query Parameters
- **page** (integer) - Optional - The page number for pagination.
- **limit** (integer) - Optional - The number of heroes to return per page.

### Response
#### Success Response (200)
- **heroes** (array) - An array of hero objects.
- **total** (integer) - The total number of heroes available.
- **page** (integer) - The current page number.

### Response Example
```json
{
  "heroes": [
    { "id": "1", "name": "Iron Man", "role": "Damage", ... },
    { "id": "2", "name": "Spider-Man", "role": "Support", ... }
  ],
  "total": 50,
  "page": 1
}
```

## GET /heroes/{name}

### Description
Retrieves detailed information for a specific hero.

### Method
GET

### Endpoint
/heroes/{name}

### Path Parameters
- **name** (string) - Required - The name of the hero to retrieve.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the hero.
- **name** (string) - The name of the hero.
- **role** (string) - The role of the hero (e.g., Damage, Support, Tank).
- **abilities** (array) - A list of the hero's abilities.
- **lore** (string) - The background story of the hero.

### Response Example
```json
{
  "id": "1",
  "name": "Iron Man",
  "role": "Damage",
  "abilities": ["Repulsor Rays", "Unibeam"],
  "lore": "Genius, billionaire, playboy, philanthropist..."
}
```

## GET /heroes/stats/{name}

### Description
Retrieves performance statistics for a specific hero.

### Method
GET

### Endpoint
/heroes/stats/{name}

### Path Parameters
- **name** (string) - Required - The name of the hero whose stats are to be retrieved.

### Response
#### Success Response (200)
- **pickRate** (float) - The percentage of matches the hero is picked.
- **winRate** (float) - The win rate of the hero.
- **avgDamage** (float) - The average damage dealt by the hero.
- **avgHealing** (float) - The average healing done by the hero.

### Response Example
```json
{
  "pickRate": 0.15,
  "winRate": 0.52,
  "avgDamage": 1200.5,
  "avgHealing": 300.2
}
```

## GET /heroes/leaderboard/{name}

### Description
Retrieves the leaderboard for a specific hero on a given platform.

### Method
GET

### Endpoint
/heroes/leaderboard/{name}

### Path Parameters
- **name** (string) - Required - The name of the hero.

### Query Parameters
- **platform** (string) - Optional - The platform for the leaderboard. Options: "pc", "ps", "xbox". Defaults to "pc".

### Response
#### Success Response (200)
- **hero** (string) - The name of the hero.
- **platform** (string) - The platform for the leaderboard.
- **rankings** (array) - An array of player rankings.

### Response Example
```json
{
  "hero": "Hulk",
  "platform": "ps",
  "rankings": [
    { "rank": 1, "player": "PlayerOne", "score": 10000 },
    { "rank": 2, "player": "PlayerTwo", "score": 9500 }
  ]
}
```

## GET /heroes/{heroName}/costumes

### Description
Retrieves a list of all available costumes for a specific hero.

### Method
GET

### Endpoint
/heroes/{heroName}/costumes

### Path Parameters
- **heroName** (string) - Required - The name of the hero.

### Response
#### Success Response (200)
- **hero** (string) - The name of the hero.
- **costumes** (array) - An array of costume objects.

### Response Example
```json
{
  "hero": "Black Panther",
  "costumes": [
    { "id": "c1", "name": "Classic", "rarity": "Common", ... },
    { "id": "c2", "name": "Vibranium", "rarity": "Epic", ... }
  ]
}
```

## GET /heroes/{heroName}/costumes/{costumeName}

### Description
Retrieves details for a specific costume of a hero.

### Method
GET

### Endpoint
/heroes/{heroName}/costumes/{costumeName}

### Path Parameters
- **heroName** (string) - Required - The name of the hero.
- **costumeName** (string) - Required - The name of the costume.

### Response
#### Success Response (200)
- **hero** (string) - The name of the hero.
- **costume** (object) - The details of the costume.

### Response Example
```json
{
  "hero": "Iron Man",
  "costume": {
    "id": "c3",
    "name": "Mark 85",
    "rarity": "Legendary",
    "imageUrl": "http://example.com/mark85.png"
  }
}
```
```

--------------------------------

### Match History (v1)

Source: https://context7.com/marvelrivalsapi/marvelrivalsapi-wrapper/llms.txt

The v1 match history endpoint provides similar functionality with the original API format.

```APIDOC
## Match History (v1)

### Description
The v1 match history endpoint provides similar functionality with the original API format.

### Method
GET

### Endpoint
/api/v1/matchhistory/{playerName}

### Parameters
#### Path Parameters
- **playerName** (string) - Required - The name of the player whose match history is to be retrieved.

#### Query Parameters
- **season** (integer) - Optional - Filter by season number.
- **skip** (integer) - Optional - Number of matches to skip for pagination.
- **game_mode** (integer) - Optional - Filter by game mode ID.
- **timestamp** (integer) - Optional - Unix timestamp to filter matches occurring after this time.

### Request Example
```javascript
const MarvelRivals = require("marvelrivalsapi");
const API = new MarvelRivals.API("YOUR_API_KEY");

async function getMatchHistoryV1() {
    try {
        const history = await API.matchhistoryv1.findPlayerMatchHistory("PlayerName", {
            season: 1,
            skip: 20,
            game_mode: 0,
            timestamp: 1704067200
        });
        console.log(history);
    } catch (error) {
        console.error("Error:", error.message);
    }
}

getMatchHistoryV1();
```

### Response
#### Success Response (200)
- **matches** (array) - An array of match objects.
- **pagination** (object) - Pagination details.
  - **skip** (integer) - Number of matches skipped.
  - **total** (integer) - Total number of matches available.

#### Response Example
```json
{
  "matches": [
    { "matchId": "old_match_id", "date": "2023-01-01T10:00:00Z", "result": "loss" }
  ],
  "pagination": {
    "skip": 20,
    "total": 100
  }
}
```
```

--------------------------------

### Achievements API

Source: https://context7.com/marvelrivalsapi/marvelrivalsapi-wrapper/llms.txt

Access in-game achievements with pagination and individual achievement lookup.

```APIDOC
## GET /achievements

### Description
Retrieves a paginated list of all in-game achievements.

### Method
GET

### Endpoint
/achievements

### Query Parameters
- **page** (integer) - Optional - The page number for pagination.
- **limit** (integer) - Optional - The number of achievements to return per page.

### Response
#### Success Response (200)
- **achievements** (array) - An array of achievement objects.
- **total** (integer) - The total number of achievements available.
- **page** (integer) - The current page number.

### Response Example
```json
{
  "achievements": [
    { "id": "a1", "name": "First Victory", "description": "Win your first match", "points": 10 },
    { "id": "a2", "name": "Level Up", "description": "Reach level 10", "points": 20 }
  ],
  "total": 100,
  "page": 1
}
```

## GET /achievements/{idOrName}

### Description
Retrieves details for a specific achievement by its ID or name.

### Method
GET

### Endpoint
/achievements/{idOrName}

### Path Parameters
- **idOrName** (string) - Required - The ID or name of the achievement.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the achievement.
- **name** (string) - The name of the achievement.
- **description** (string) - The description of the achievement.
- **points** (integer) - The points awarded for completing the achievement.
- **requirements** (object) - The requirements to unlock the achievement.

### Response Example
```json
{
  "id": "first_victory",
  "name": "First Victory",
  "description": "Win your first match",
  "points": 10,
  "requirements": { "condition": "win_match", "count": 1 }
}
```
```

--------------------------------

### Match Details

Source: https://context7.com/marvelrivalsapi/marvelrivalsapi-wrapper/llms.txt

Retrieve detailed information about a specific match using its unique match ID.

```APIDOC
## Match Details

### Description
Retrieve detailed information about a specific match using its unique match ID.

### Method
GET

### Endpoint
/api/matchdetails/{matchId}

### Parameters
#### Path Parameters
- **matchId** (string) - Required - The unique identifier of the match.

### Request Example
```javascript
const MarvelRivals = require("marvelrivalsapi");
const API = new MarvelRivals.API("YOUR_API_KEY");

async function getMatchDetails() {
    try {
        const matchDetails = await API.match.getMatchDetails("match_uid_12345");
        console.log(matchDetails);
    } catch (error) {
        console.error("Match not found:", error.message);
    }
}

getMatchDetails();
```

### Response
#### Success Response (200)
- **matchId** (string) - The unique ID of the match.
- **date** (string) - The date and time the match occurred (ISO 8601 format).
- **duration** (integer) - The duration of the match in seconds.
- **map** (string) - The name of the map where the match took place.
- **gameMode** (string) - The game mode of the match.
- **teams** (array) - An array representing the teams involved in the match.
  - **players** (array) - An array of players in the team.
  - **score** (integer) - The score of the team.

#### Response Example
```json
{
  "matchId": "match_uid_12345",
  "date": "2024-01-15T20:30:00Z",
  "duration": 1245,
  "map": "Tokyo 2099",
  "gameMode": "Competitive",
  "teams": [
    {
      "players": [ { "playerName": "Player1", "hero": "HeroA" }, { "playerName": "Player2", "hero": "HeroB" } ],
      "score": 3
    },
    {
      "players": [ { "playerName": "Player3", "hero": "HeroC" }, { "playerName": "Player4", "hero": "HeroD" } ],
      "score": 2
    }
  ]
}
```
```

--------------------------------

### Access Enhanced Hero Data (v2)

Source: https://context7.com/marvelrivalsapi/marvelrivalsapi-wrapper/llms.txt

Retrieve hero data with support for field selection to optimize response payloads.

```javascript
const MarvelRivals = require("marvelrivalsapi");
const API = new MarvelRivals.API("YOUR_API_KEY");

// Get full heroes list
async function getHeroesV2() {
    try {
        const heroes = await API.heroesv2.getHeroes();
        console.log(heroes);
        // Returns complete hero list with v2 data structure
    } catch (error) {
        console.error("Error:", error.message);
    }
}

// Get specific hero with field selection
async function getHeroV2() {
    try {
        // Get all fields
        const fullHero = await API.heroesv2.getHero("Thor");
        console.log(fullHero);

        // Get only specific fields (comma-separated string)
        const partialHero = await API.heroesv2.getHero("Thor", "id,name,role");
        console.log(partialHero);
        // Returns: { id: 15, name: "Thor", role: "Vanguard" }

        // Get specific fields (array format)
        const selectedFields = await API.heroesv2.getHero("Scarlet Witch", ["id", "name", "abilities", "role"]);
        console.log(selectedFields);
        // Returns only the requested fields
    } catch (error) {
        console.error("Hero not found:", error.message);
    }
}

getHeroesV2();
getHeroV2();
```

--------------------------------

### Access In-Game Achievements

Source: https://context7.com/marvelrivalsapi/marvelrivalsapi-wrapper/llms.txt

Retrieve achievement lists with pagination or look up specific achievements by ID or name.

```javascript
const MarvelRivals = require("marvelrivalsapi");
const API = new MarvelRivals.API("YOUR_API_KEY");

// Get all achievements with pagination
async function getAllAchievements() {
    try {
        const achievements = await API.achievements.getAllAchievements({
            page: 1,
            limit: 10
        });
        console.log(achievements);
        // Returns: { achievements: [{ id, name, description, points, ... }], total, page }
    } catch (error) {
        console.error("Error:", error.message);
    }
}

// Get specific achievement by ID or name
async function getAchievement() {
    try {
        const achievement = await API.achievements.getAchievement("first_victory");
        console.log(achievement);
        // Returns: { id, name, description, points, requirements, ... }
    } catch (error) {
        console.error("Achievement not found:", error.message);
    }
}

getAllAchievements();
getAchievement();
```

--------------------------------

### Update Player Data (v2)

Source: https://context7.com/marvelrivalsapi/marvelrivalsapi-wrapper/llms.txt

Refresh player data using the v2 endpoint. This asynchronous operation updates the cached information for the specified player. Ensure correct player identification and handle potential errors.

```javascript
const MarvelRivals = require("marvelrivalsapi");
const API = new MarvelRivals.API("YOUR_API_KEY");

// Update player data
async function updatePlayerV2() {
    try {
        const result = await API.playerv2.updatePlayer("PlayerName");
        console.log("Player data refreshed:", result);
    } catch (error) {
        console.error("Update failed:", error.message);
    }
}

updatePlayerV2();
```

--------------------------------

### Heroes (v2) API

Source: https://context7.com/marvelrivalsapi/marvelrivalsapi-wrapper/llms.txt

The v2 heroes endpoint provides enhanced hero data with field selection for optimized responses.

```APIDOC
## GET /v2/heroes

### Description
Retrieves the complete list of heroes with the v2 data structure.

### Method
GET

### Endpoint
/v2/heroes

### Response
#### Success Response (200)
- Returns the complete hero list with v2 data structure.

### Response Example
```json
[
  { "id": 1, "name": "Thor", "role": "Vanguard", ... },
  { "id": 2, "name": "Iron Man", "role": "Damage", ... }
]
```

## GET /v2/heroes/{name}

### Description
Retrieves specific hero data, with options for field selection.

### Method
GET

### Endpoint
/v2/heroes/{name}

### Path Parameters
- **name** (string) - Required - The name of the hero.

### Query Parameters
- **fields** (string or array) - Optional - Comma-separated string or array of fields to include in the response (e.g., "id,name,role" or ["id", "name", "role"]).

### Response
#### Success Response (200)
- Returns the requested hero data with the specified fields.

### Response Example (Specific Fields)
```json
{
  "id": 15,
  "name": "Thor",
  "role": "Vanguard"
}
```

### Response Example (All Fields)
```json
{
  "id": 15,
  "name": "Thor",
  "role": "Vanguard",
  "abilities": ["Mjolnir", "Lightning Strike"],
  "lore": "God of Thunder..."
}
```
```

--------------------------------

### Update Player Profile Data (v1)

Source: https://context7.com/marvelrivalsapi/marvelrivalsapi-wrapper/llms.txt

Trigger an update for a player's profile data. This action refreshes the cached data associated with the player's profile on the API. Ensure the player name is correct to avoid update failures.

```javascript
const MarvelRivals = require("marvelrivalsapi");
const API = new MarvelRivals.API("YOUR_API_KEY");

// Trigger a player profile update (refreshes cached data)
async function updatePlayer() {
    try {
        const result = await API.player.updatePlayer("PlayerName");
        console.log("Profile updated:", result);
    } catch (error) {
        console.error("Update failed:", error.message);
    }
}

updatePlayer();
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.