marketplace-v2-history-endpoint.md

Marketplace V2: New & Updated Endpoints

1. GET /marketplace/v2/bids/my — Updated Response

New field added: filledByAddress

The response for filled bids now includes the address that filled the offer.

{
  "code": 200,
  "success": true,
  "data": [
    {
      "id": "abc123",
      "tokenId": 42,
      "price": "1000000000000000000",
      "paymentToken": "0x...",
      "buyer": "0xYourAddress",
      "deadline": "1700000000",
      "status": "filled",
      "filledAt": "2025-01-15T10:30:00Z",
      "filledTxHash": "0x...",
      "filledByAddress": "0xSellerAddress",  // NEW — who filled this bid
      "investment": {
        "nftId": "42",
        "ftAmount": "500000000000000000",
        "amountRemaining": "800000000000000000",
        "amountInvested": "1000000000000000000",
        "token": "0x...",
        "strike": "1500000000",
        "investor": "0x...",
        "recipient": "0x...",
        "holder": "0x...",
        "timestamp": "1699000000"
      }
    }
  ],
  "total": 1,
  "limit": 30,
  "offset": 0
}

• filledByAddress is null/omitted for active, cancelled, and expired bids
• Also appears in GET /marketplace/v2/history/bids responses

---

2. GET /marketplace/v2/history — NEW Combined History Endpoint

Returns all marketplace sales where the user was either buyer or seller, in a single paginated list.

Query Parameters

Param	Type	Required	Description
chainId	int	Yes	Chain ID (e.g., 146 for Sonic)
address	string	Yes	Wallet address (matches buyer OR seller)
limit	int	No	1–100, default 30
offset	int	No	>= 0, default 0
sortBy	string	No	price, timestamp, tokenId, ftAmount, amountRemaining
sortOrder	string	No	asc or desc
sortByUsd	bool	No	Sort by USD value instead of raw amount
paymentToken	string	No	Filter by payment token address
minTimestamp	int	No	Min sale timestamp (epoch seconds)
maxTimestamp	int	No	Max sale timestamp (epoch seconds)
minPrice	string	No	Min sale price (raw wei)
maxPrice	string	No	Max sale price (raw wei)
minPriceUsd	float	No	Min sale price in USD
maxPriceUsd	float	No	Max sale price in USD
collateralToken	string	No	Filter by investment collateral token
minFtAmount	string	No	Min FT amount filter
maxFtAmount	string	No	Max FT amount filter
minAmountRemaining	string	No	Min capital remaining filter
maxAmountRemaining	string	No	Max capital remaining filter

Example Request

GET /marketplace/v2/history?chainId=146&address=0xYourAddress&sortBy=timestamp&sortOrder=desc&limit=20

Example Response

{
  "code": 200,
  "success": true,
  "data": [
    {
      "id": "sale_001",
      "buyer": "0xYourAddress",
      "seller": "0xOtherAddress",
      "price": "2000000000000000000",
      "token": "0xPaymentToken",
      "tokenId": "42",
      "timestamp": "1700100000",
      "makerFee": "10000000000000000",
      "takerFee": "10000000000000000",
      "txHash": "0x...",
      "investmentId": "42",
      "role": "buyer",  // NEW — "buyer" or "seller"
      "investment": {
        "nftId": "42",
        "ftAmount": "500000000000000000",
        "amountRemaining": "800000000000000000",
        "amountInvested": "1000000000000000000",
        "token": "0xCollateralToken",
        "strike": "1500000000",
        "investor": "0xOriginalInvestor",
        "recipient": "0xCurrentOwner",
        "holder": "0xCurrentOwner",
        "timestamp": "1699000000"
      }
    },
    {
      "id": "sale_002",
      "buyer": "0xSomeoneElse",
      "seller": "0xYourAddress",
      "price": "1500000000000000000",
      "token": "0xPaymentToken",
      "tokenId": "99",
      "timestamp": "1700050000",
      "makerFee": "7500000000000000",
      "takerFee": "7500000000000000",
      "txHash": "0x...",
      "investmentId": "99",
      "role": "seller",  // User was the seller here
      "investment": { ... }
    }
  ],
  "total": 25,
  "limit": 20,
  "offset": 0
}

Notes

• The role field is only set on this combined endpoint. The existing /history/sold and /history/bought endpoints are unchanged (no role field).
• The response shape (V2SaleWithInvestment) is identical to /history/sold and /history/bought, plus the role field.
• Pagination, sorting, and USD filtering work exactly the same as the existing history endpoints.
• Self-trades (user is both buyer and seller) will show role: "seller".

---

Existing Endpoints (unchanged)

These still work exactly as before:

• GET /marketplace/v2/history/sold — requires seller param
• GET /marketplace/v2/history/bought — requires buyer param
• GET /marketplace/v2/history/bids — requires buyer param (filled bids only, now includes filledByAddress)