API Reference

User

Market

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Get user's markets (lend + borrow debt/collateral) for a specific asset

GET/api/v1/users/{address}/markets/merged/lookup

Get user's markets (lend + borrow debt/collateral) for a specific asset

Path ParametersExpand Collapse

address: string

The user account address

Query ParametersExpand Collapse

asset_id: string

Asset ID for lookup

with_text: optional boolean

Include text variation fields

with_value: optional boolean

Calculate and include USD values for amounts, where applicable

ReturnsExpand Collapse

data: UserMergedMarket { asset_info, borrow_collateral, borrow_debt, lend }

User market allocations grouped by asset.

Note: because of the inverted structure of merged market accounts, account health cannot be represented and is excluded in the merged structures.

asset_info: AssetInfo { asset, classification, metadata }

Asset identifiers with associated metadata

asset: AssetSpec { id, group, group_key }

Provides a unique identifier for an asset for use throughout the Neptune API. IDs are unique across asset domains (contract tokens, native denoms, etc)

id: string

group: "native" or "token"

One of the following:

"native"

"token"

group_key: string

classification: AssetClassification

The asset's classification metadata. Assets are classfied to provide context on their usage throughout the Neptune API (e.g. regular assets, neptune receipt tokens, LSTs, etc.)

Each asset belongs to only a single classification type. This object contains metadata pertaining to the given classification.

While some fields may be common among the distinct classifcations, each classification is distinct and subject to independent change.

One of the following:

Regular = object { kind, neptune_receipt_asset }

kind: "regular"

neptune_receipt_asset: AssetSpec { id, group, group_key }

Provides a unique identifier for an asset for use throughout the Neptune API. IDs are unique across asset domains (contract tokens, native denoms, etc)

id: string

group: "native" or "token"

One of the following:

"native"

"token"

group_key: string

NeptuneReceiptToken = object { kind, origin_asset }

kind: "neptune_receipt_token"

origin_asset: AssetSpec { id, group, group_key }

Provides a unique identifier for an asset for use throughout the Neptune API. IDs are unique across asset domains (contract tokens, native denoms, etc)

id: string

group: "native" or "token"

One of the following:

"native"

"token"

group_key: string

LiquidStakingToken = object { kind, origin_asset }

kind: "liquid_staking_token"

origin_asset: AssetSpec { id, group, group_key }

Provides a unique identifier for an asset for use throughout the Neptune API. IDs are unique across asset domains (contract tokens, native denoms, etc)

id: string

group: "native" or "token"

One of the following:

"native"

"token"

group_key: string

metadata: AssetMetadata { decimals_denom, decimals_display, name, 2 more }

Additional metadata for assets

decimals_denom: number

Denom exponent, or num. of decimal places that shift between denom/standard amounts (e.g. 18 for INJ)

formatuint32

minimum0

decimals_display: number

Number of decimals used when displaying amounts of this asset (this is subjective and used for generating text representations)

formatuint32

minimum0

name: string

Full name of the asset

symbol: string

Symbol of the asset, e.g.: NEPT INJ

symbol_denom: string

Denom symbol for the asset (e.g. inj for INJ, sat for BTC)

borrow_collateral: array of UserCollateralAccountPool { amount, extra, index }

User collateral contribution for asset in borrow market, listed by subaccount

amount: string

Amount of this asset which is actively collateralized

extra: object { text, value }

text: object { amount }

Human-readable field variants. Will not be null when query param with_text is true.

amount: string

value: object { amount, extra, price }

USD values for the corresponding amounts above. Will not be null when query param with_value is true.

Note

This variant group contains an additional price field (set to the number used in value calculation).

The embedded text group will contain the text variant if with_text was specified as well.

amount: string

extra: object { text }

text: object { amount, price }

Human-readable variants of USD values. Will not be null when query params with_text and with_value are true.

amount: string

price: string

Text representation of price

price: string

Price used in value calculations

index: number

Account index

formatuint8

minimum0

maximum255

borrow_debt: array of UserDebtAccountPool { extra, index, principal, shares }

User debt contribution for asset in borrow market, listed by subaccount

extra: object { text, value }

text: object { principal, shares }

Human-readable field variants. Will not be null when query param with_text is true.

principal: string

shares: string

value: object { extra, price, principal, shares }

USD values for the corresponding amounts above. Will not be null when query param with_value is true.

Note

This variant group contains an additional price field (set to the number used in value calculation).

The embedded text group will contain the text variant if with_text was specified as well.

extra: object { text }

text: object { price, principal, shares }

Human-readable variants of USD values. Will not be null when query params with_text and with_value are true.

price: string

Text representation of price

principal: string

shares: string

price: string

Price used in value calculations

principal: string

shares: string

index: number

Account index

formatuint8

minimum0

maximum255

principal: string

Initial amount borrowed (of debts which have not yet been repaid)

shares: string

lend: optional object { origin_equivalent, receipt_amounts }

User contribution for asset's lending market, if one exists

origin_equivalent: UserLendOriginAmounts { collateralized, extra, held, total }

The lending amounts converted into the equivalent for the receipt token's origin/source asset

collateralized: string

Total equivalent amount of origin token collateralized across this user's borrowing portfolio

NOTE: This is not the amount of the origin asset that the user holds, but the amount held in the receipt token rendered as the equivalent amount in the origin asset.

Or, more formally: origin_equivalent_collateralized = receipt_collateralized / receipt_redemption_ratio

extra: object { text }

text: object { collateralized, held, total }

Human-readable field variants. Will not be null when query param with_text is true.

collateralized: string

held: string

total: string

held: string

Total equivalent amount of origin token held in address balance

NOTE: This is not the amount of the origin asset that the user holds, but the amount held in the receipt token rendered as the equivalent amount in the origin asset.

Or, more formally: origin_equivalent_held = receipt_held / receipt_redemption_ratio

total: string

Total of held and collateralized equivalent for origin asset

Or, more formally: origin_equivalent_total = receipt_lent_total / receipt_redemption_ratio

receipt_amounts: UserLendReceiptAmounts { collateralized, extra, held, total }

The lending amounts in the original receipt token amounts

collateralized: string

Total amount of receipt token collateralized across this user's borrowing portfolio

extra: object { text, value }

text: object { collateralized, held, total }

Human-readable field variants. Will not be null when query param with_text is true.

collateralized: string

held: string

total: string

value: object { collateralized, extra, held, 2 more }

USD values for the corresponding amounts above. Will not be null when query param with_value is true.

Note

This variant group contains an additional price field (set to the number used in value calculation).

The embedded text group will contain the text variant if with_text was specified as well.

collateralized: string

extra: object { text }

text: object { collateralized, held, price, total }

Human-readable variants of USD values. Will not be null when query params with_text and with_value are true.

collateralized: string

held: string

price: string

Text representation of price

total: string

held: string

price: string

Price used in value calculations

total: string

held: string

Total amount of receipt token held in address balance

total: string

Sum of receipt amount held and receipt amount collateralized

error: unknown

Error data. Guaranteed null for successful response.

status: number

HTTP status. Successful responses are guaranteed to be < 400. Conversely, error responses are guaranteed to be >= 400.

formatuint16

minimum0

maximum65535

status_text: string

HTTP status text

Get user's markets (lend + borrow debt/collateral) for a specific asset

HTTP

HTTP

TypeScript

Python

curl https://api-v2.nept.finance/api/v1/users/$ADDRESS/markets/merged/lookup

200 example

500 example

{
  "data": {
    "asset_info": {
      "asset": {
        "id": "native;inj",
        "group": "native",
        "group_key": "inj"
      },
      "metadata": {
        "name": "Injective",
        "symbol": "INJ",
        "symbol_denom": "inj",
        "decimals_denom": 18,
        "decimals_display": 4
      },
      "classification": {
        "kind": "regular",
        "neptune_receipt_asset": {
          "id": "token;inj1rmzufd7h09sqfrre5dtvu5d09ta7c0t4jzkr2f",
          "group": "token",
          "group_key": "inj1rmzufd7h09sqfrre5dtvu5d09ta7c0t4jzkr2f"
        }
      }
    },
    "lend": {
      "receipt_amounts": {
        "held": "643195861442194223248",
        "collateralized": "730834802009981512361",
        "total": "1374030663452175735609",
        "extra": {
          "text": {
            "total": "1,374.0306 nINJ",
            "held": "643.1958 nINJ",
            "collateralized": "730.8348 nINJ"
          },
          "value": {
            "held": "2073.942860417499929371",
            "collateralized": "2356.528875006543036615",
            "price": "3.224434398205298254",
            "total": "4430.471735424042965987",
            "extra": {
              "text": {
                "price": "$3.22",
                "collateralized": "$2,356.52",
                "held": "$2,073.94",
                "total": "$4,430.47"
              }
            }
          }
        }
      },
      "origin_equivalent": {
        "held": "689841691284211618706",
        "collateralized": "783836380317316233638",
        "total": "1473678071601527852345",
        "extra": {
          "text": {
            "total": "1,473.6780 INJ",
            "collateralized": "783.8363 INJ",
            "held": "689.8416 INJ"
          }
        }
      }
    },
    "borrow_collateral": [
      {
        "index": 0,
        "amount": "745856805244361991671",
        "extra": {
          "text": {
            "amount": "745.8568 INJ"
          },
          "value": {
            "price": "2.99835",
            "amount": "2236.339752004432777726",
            "extra": {
              "text": {
                "amount": "$2,236.33",
                "price": "$2.99"
              }
            }
          }
        }
      }
    ],
    "borrow_debt": [
      {
        "index": 0,
        "principal": "64722195311136316616",
        "shares": "64722195311136316616",
        "extra": {
          "text": {
            "principal": "64.7221 INJ",
            "shares": "64.7221 INJ"
          },
          "value": {
            "shares": "194.059794311145574925",
            "price": "2.99835",
            "principal": "194.059794311145574925",
            "extra": {
              "text": {
                "shares": "$194.05",
                "price": "$2.99",
                "principal": "$194.05"
              }
            }
          }
        }
      }
    ]
  },
  "error": null,
  "status": 200,
  "status_text": "200 OK"
}

{
  "data": null,
  "error": {
    "kind": "internal",
    "scope": "server",
    "message": "An unexpected error occurred"
  },
  "status": 500,
  "status_text": "500 Internal Server Error"
}

Returns Examples

200 example

500 example

{
  "data": {
    "asset_info": {
      "asset": {
        "id": "native;inj",
        "group": "native",
        "group_key": "inj"
      },
      "metadata": {
        "name": "Injective",
        "symbol": "INJ",
        "symbol_denom": "inj",
        "decimals_denom": 18,
        "decimals_display": 4
      },
      "classification": {
        "kind": "regular",
        "neptune_receipt_asset": {
          "id": "token;inj1rmzufd7h09sqfrre5dtvu5d09ta7c0t4jzkr2f",
          "group": "token",
          "group_key": "inj1rmzufd7h09sqfrre5dtvu5d09ta7c0t4jzkr2f"
        }
      }
    },
    "lend": {
      "receipt_amounts": {
        "held": "643195861442194223248",
        "collateralized": "730834802009981512361",
        "total": "1374030663452175735609",
        "extra": {
          "text": {
            "total": "1,374.0306 nINJ",
            "held": "643.1958 nINJ",
            "collateralized": "730.8348 nINJ"
          },
          "value": {
            "held": "2073.942860417499929371",
            "collateralized": "2356.528875006543036615",
            "price": "3.224434398205298254",
            "total": "4430.471735424042965987",
            "extra": {
              "text": {
                "price": "$3.22",
                "collateralized": "$2,356.52",
                "held": "$2,073.94",
                "total": "$4,430.47"
              }
            }
          }
        }
      },
      "origin_equivalent": {
        "held": "689841691284211618706",
        "collateralized": "783836380317316233638",
        "total": "1473678071601527852345",
        "extra": {
          "text": {
            "total": "1,473.6780 INJ",
            "collateralized": "783.8363 INJ",
            "held": "689.8416 INJ"
          }
        }
      }
    },
    "borrow_collateral": [
      {
        "index": 0,
        "amount": "745856805244361991671",
        "extra": {
          "text": {
            "amount": "745.8568 INJ"
          },
          "value": {
            "price": "2.99835",
            "amount": "2236.339752004432777726",
            "extra": {
              "text": {
                "amount": "$2,236.33",
                "price": "$2.99"
              }
            }
          }
        }
      }
    ],
    "borrow_debt": [
      {
        "index": 0,
        "principal": "64722195311136316616",
        "shares": "64722195311136316616",
        "extra": {
          "text": {
            "principal": "64.7221 INJ",
            "shares": "64.7221 INJ"
          },
          "value": {
            "shares": "194.059794311145574925",
            "price": "2.99835",
            "principal": "194.059794311145574925",
            "extra": {
              "text": {
                "shares": "$194.05",
                "price": "$2.99",
                "principal": "$194.05"
              }
            }
          }
        }
      }
    ]
  },
  "error": null,
  "status": 200,
  "status_text": "200 OK"
}

{
  "data": null,
  "error": {
    "kind": "internal",
    "scope": "server",
    "message": "An unexpected error occurred"
  },
  "status": 500,
  "status_text": "500 Internal Server Error"
}