my-puts-endpoint.md

New Endpoint: GET /marketplace/v2/puts/my/puts

What it does

Returns all of a user's PUTs in a single query — combining what my/on-sale and my/on-hold already do, plus PUTs with active offers. This lets you build a unified "My PUTs" view without multiple API calls.

Base URL

GET /marketplace/v2/puts/my/puts?chainId={chainId}&owner={address}

Response Shape

Same V2Response as all other V2 endpoints:

{
  "code": 200,
  "success": true,
  "data": [
    {
      "id": "146_42",
      "nftId": "42",
      "ftAmount": "1000000000000000000",
      "amountRemaining": "500000000000000000",
      "amountInvested": "1000000000000000000",
      "token": "0x...",
      "strike": "...",
      "investor": "0x...",
      "recipient": "0x...",
      "holder": "0x...",
      "timestamp": "1700000000",
      "exited": false,
      "lastListingId": "abc-123",
      "lastListingExpires": "1700100000",
      "lastListing": {
        "id": "abc-123",
        "token": "0x...",
        "seller": "0x...",
        "tokenId": "42",
        "price": "500000000",
        "expires": "1700100000",
        "status": "ACTIVE"
      },
      "lastSold": null,
      "bestOffer": {
        "id": "offer-456",
        "price": "400000000",
        "paymentToken": "0x...",
        "buyer": "0x...",
        "deadline": "1700200000"
      }
    }
  ],
  "total": 15,
  "limit": 30,
  "offset": 0
}

• lastListing is null when the PUT has no active listing (on-hold)
• bestOffer is null when no active offers exist for that PUT
• Items with a listing are verified on-chain (invalid listings are filtered out, same as my/on-sale)

Subset Filters (boolean toggles)

These control which categories of PUTs to include. All default to true (include everything).

Parameter	Default	Effect when false
isSale	true	Exclude PUTs with active listings
isHold	true	Exclude PUTs without active listings
isOffer	true	Exclude PUTs with active offers

These are combined with OR logic:

• ?isSale=true&isHold=false&isOffer=false → only listed PUTs (same as my/on-sale)
• ?isSale=false&isHold=true → only unlisted PUTs (same as my/on-hold)
• ?isSale=false&isHold=false&isOffer=true → only PUTs that have offers
• No params / all true → everything

All Query Parameters

Required

Parameter	Type	Description
chainId	int	Chain ID (e.g. 146)
owner	string	Wallet address

Pagination & Sorting

Parameter	Type	Default	Description
limit	int	30	1–100
offset	int	0	>= 0
sortBy	string	nftId	One of: nftId, ftAmount, amountRemaining, price, expires, timestamp, offerPrice, offerDeadline
sortOrder	string	desc	asc or desc
sortByUsd	bool	false	Sort by USD-converted value

Investment Filters

Parameter	Type	Description
collateralToken	address	Filter by collateral token
minFtAmount / maxFtAmount	string	FT amount range (raw wei)
minFtAmountUsd / maxFtAmountUsd	float	FT amount range (USD)
minAmountRemaining / maxAmountRemaining	string	Capital remaining range (raw)
minAmountRemainingUsd / maxAmountRemainingUsd	float	Capital remaining range (USD)

Listing Filters

These use a guard pattern — PUTs without listings pass through unaffected.

Parameter	Type	Description
listingToken	address	Filter by listing payment token
minListingPrice / maxListingPrice	string	Listing price range (raw)
minListingPriceUsd / maxListingPriceUsd	float	Listing price range (USD)
minExpires / maxExpires	int64	Listing expiry range (unix timestamp)

Offer Filters

These also use the guard pattern — PUTs without offers pass through unaffected.

Parameter	Type	Description
offerToken	address	Filter by offer payment token
minOfferPrice / maxOfferPrice	string	Offer price range (raw)
minOfferPriceUsd / maxOfferPriceUsd	float	Offer price range (USD)
minOfferDeadline / maxOfferDeadline	int64	Offer deadline range (unix timestamp)

Special

Parameter	Type	Default	Description
filterByPriceDiff	bool	false	Only return PUTs where best offer USD > amount remaining USD

Example Requests

# All my PUTs
GET /marketplace/v2/puts/my/puts?chainId=146&owner=0xABC...

# Only on-sale, sorted by listing price descending
GET /marketplace/v2/puts/my/puts?chainId=146&owner=0xABC...&isSale=true&isHold=false&isOffer=false&sortBy=price&sortOrder=desc

# Only PUTs with offers, sorted by offer price in USD
GET /marketplace/v2/puts/my/puts?chainId=146&owner=0xABC...&isSale=false&isHold=false&isOffer=true&sortBy=offerPrice&sortByUsd=true

# All PUTs where offer > remaining value (profitable to accept)
GET /marketplace/v2/puts/my/puts?chainId=146&owner=0xABC...&filterByPriceDiff=true

# Paginated with USD filters
GET /marketplace/v2/puts/my/puts?chainId=146&owner=0xABC...&minFtAmountUsd=100&maxFtAmountUsd=1000&limit=10&offset=0

Notes

• On-chain verification: Listings are verified on-chain before returning (same as my/on-sale). Invalid listings (revoked approval, ownership changed) are automatically filtered out.
• Guard pattern: Listing/offer filters only apply to items that have a listing/offer. Items without one always pass through. This means setting minListingPrice=1000 won't exclude on-hold items — it only filters among listed ones.
• Existing endpoints still work: my/on-sale and my/on-hold are unchanged. This new endpoint is additive.