> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getnimbus.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get DEFI positions for an address

> Retrieves DEFI position information for a given address across various chains and protocols



## OpenAPI

````yaml /api-reference/openapi.json get /v2/address/{address}/positions
openapi: 3.0.0
info:
  title: Nimbus API
  version: 1.0.0
  description: >-
    API for Nimbus


    ## Rate Limiting

    This API implements rate limiting to ensure fair usage and protect our
    services. The current rate limit is:


    - **40 requests per 1 minute** per IP address


    If you exceed this limit, you will receive a 429 (Too Many Requests)
    response. Please wait for the rate limit window to reset before making
    additional requests.


    If you need more, please contact us at **thanhle@getnimbus.io** or TG
    **@thanhle27** to get premium API Key.
servers:
  - url: https://api.getnimbus.io
    description: API server
security: []
tags: []
paths:
  /v2/address/{address}/positions:
    get:
      tags:
        - Address
      summary: Get DEFI positions for an address
      description: >-
        Retrieves DEFI position information for a given address across various
        chains and protocols
      parameters:
        - in: path
          name: address
          required: true
          schema:
            type: string
          example: '0x692853c81afc8f847147c8a8b4368dc894697fc12b929ef3071482d27339815e'
          description: The address to get positions for
        - in: query
          name: chain
          schema:
            type: string
          description: The blockchain to query
        - in: query
          name: protocol
          schema:
            type: string
          example: scallop,suilend
          description: >
            List of protocols to query positions separated by commas. You can
            get supported protocols from api **"/v2/defi/protocols"**
        - in: query
          name: force_refresh
          schema:
            type: boolean
          description: Whether to force refresh the positions
        - in: query
          name: slush_skip
          schema:
            type: boolean
          description: >
            When true, filters out positions that are underlying Slush
            strategies

            (AlphaFi positions tagged SlushLending and the Slush Volo vault)
        - in: query
          name: exclude_protocol
          schema:
            type: string
          example: alpha-fi,volo
          description: |
            Comma-separated list of protocol slugs to exclude from results
      responses:
        '200':
          description: Successful response with position information
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      oneOf:
                        - $ref: '#/components/schemas/StakingPosition'
                        - $ref: '#/components/schemas/NativeStakingPosition'
                        - $ref: '#/components/schemas/LendingPosition'
                        - $ref: '#/components/schemas/VestPosition'
                        - $ref: '#/components/schemas/AMMPosition'
                        - $ref: '#/components/schemas/CLMMPosition'
                        - $ref: '#/components/schemas/DLMMPosition'
                        - $ref: '#/components/schemas/BorrowPosition'
                        - $ref: '#/components/schemas/FarmPosition'
                        - $ref: '#/components/schemas/PerpPosition'
                        - $ref: '#/components/schemas/MarginPosition'
        '400':
          description: Invalid address provided
        '429':
          description: Too many requests (RPC error)
        '500':
          description: Internal server error
      security:
        - apiKeyAuth: []
components:
  schemas:
    StakingPosition:
      type: object
      properties:
        positionId:
          type: string
          example: >-
            0x7016aae72cfc67f2fadf55769c0a7dd54291a583b63051a5ed71081cce836ac6::sca::SCA
        owner:
          type: string
          example: '0x7383b5e076553f79822374baca843c8fac02d510fb0f4ab344fc7ab591be94a7'
        input:
          type: array
          items:
            $ref: '#/components/schemas/TokenPosition'
        yieldCollected:
          type: array
          items:
            $ref: '#/components/schemas/TokenPosition'
        current:
          type: object
          properties:
            tokens:
              type: array
              items:
                $ref: '#/components/schemas/TokenPosition'
            yield:
              type: array
              items:
                $ref: '#/components/schemas/TokenPosition'
        fee:
          type: number
          example: 0
        chain:
          type: string
          example: SUI
        type:
          type: string
          enum:
            - Staking
          example: Staking
        farming:
          type: array
          items:
            $ref: '#/components/schemas/FarmingInfo'
        meta:
          type: object
          properties:
            protocol:
              $ref: '#/components/schemas/ProtocolMeta'
    NativeStakingPosition:
      type: object
      properties:
        positionId:
          type: string
          example: '0xb8068ad94d7f0448059ae3ea1d877f2af54792b2849d80e2753201adfa532411'
        owner:
          type: string
          example: '0x7383b5e076553f79822374baca843c8fac02d510fb0f4ab344fc7ab591be94a7'
        input:
          type: array
          items:
            $ref: '#/components/schemas/TokenPosition'
        yieldCollected:
          type: array
          items:
            $ref: '#/components/schemas/TokenPosition'
        current:
          type: object
          properties:
            tokens:
              type: array
              items:
                $ref: '#/components/schemas/TokenPosition'
            yield:
              type: array
              items:
                $ref: '#/components/schemas/TokenPosition'
            validatorInfo:
              type: object
              properties:
                name:
                  type: string
                  nullable: true
                  example: Suiet
                logo:
                  type: string
                  nullable: true
                  example: https://assets.suiet.app/logo.png
        fee:
          type: number
          example: 0
        chain:
          type: string
          example: SUI
        type:
          type: string
          enum:
            - NativeStaking
          example: NativeStaking
        farming:
          type: array
          items:
            $ref: '#/components/schemas/FarmingInfo'
        meta:
          type: object
          properties:
            protocol:
              $ref: '#/components/schemas/ProtocolMeta'
    LendingPosition:
      type: object
      properties:
        positionId:
          type: string
          example: '0x91bd1dc1cc5586706444ab8f7f9b2bf3f73e97aabb3269e03291763ed5fc4262'
        owner:
          type: string
          example: '0x7383b5e076553f79822374baca843c8fac02d510fb0f4ab344fc7ab591be94a7'
        input:
          type: array
          items:
            $ref: '#/components/schemas/TokenPosition'
        current:
          type: object
          properties:
            tokens:
              type: array
              items:
                $ref: '#/components/schemas/TokenPosition'
            yield:
              type: array
              items:
                $ref: '#/components/schemas/TokenPosition'
        fee:
          type: object
          properties:
            value:
              type: number
              example: 0
        chain:
          type: string
          enum:
            - SUI
          example: SUI
        type:
          type: string
          enum:
            - Lending
          example: Lending
        tags:
          type: array
          items:
            type: string
          example:
            - Boosted
        farming:
          type: array
          items:
            $ref: '#/components/schemas/FarmingInfo'
        meta:
          type: object
          properties:
            protocol:
              $ref: '#/components/schemas/ProtocolMeta'
    VestPosition:
      type: object
      properties:
        positionId:
          type: string
          example: '0xb8068ad94d7f0448059ae3ea1d877f2af54792b2849d80e2753201adfa532411'
        owner:
          type: string
          example: '0x7383b5e076553f79822374baca843c8fac02d510fb0f4ab344fc7ab591be94a7'
        input:
          type: array
          items:
            $ref: '#/components/schemas/TokenPosition'
        yieldCollected:
          type: array
          items:
            $ref: '#/components/schemas/TokenPosition'
        current:
          type: object
          properties:
            tokens:
              type: array
              items:
                $ref: '#/components/schemas/TokenPosition'
            yield:
              type: array
              items:
                $ref: '#/components/schemas/TokenPosition'
            endDate:
              type: string
              nullable: true
              example: '2024-12-08T00:00:00.000Z'
        chain:
          type: string
          example: SUI
        type:
          type: string
          enum:
            - Vest
          example: Vest
        farming:
          type: array
          items:
            $ref: '#/components/schemas/FarmingInfo'
        meta:
          type: object
          properties:
            protocol:
              $ref: '#/components/schemas/ProtocolMeta'
    AMMPosition:
      type: object
      properties:
        positionId:
          type: string
          example: '0xe680066288f8ae8120ff9b5a7accfede974cdfdb07bae9a38b43ee3edf505a7e'
        poolId:
          type: string
          example: 0x123...abc
        poolName:
          type: string
          example: SUI-USDC
        owner:
          type: string
          example: '0x692853c81afc8f847147c8a8b4368dc894697fc12b929ef3071482d27339815e'
        input:
          type: array
          items:
            $ref: '#/components/schemas/TokenPosition'
        yieldCollected:
          type: array
          items:
            $ref: '#/components/schemas/TokenPosition'
        current:
          type: object
          properties:
            tokens:
              type: array
              items:
                $ref: '#/components/schemas/TokenPosition'
            yield:
              type: array
              items:
                $ref: '#/components/schemas/TokenPosition'
        fee:
          type: object
          properties:
            value:
              type: number
              example: 0
        tags:
          type: array
          items:
            type: string
          example:
            - Farming
        farming:
          type: array
          items:
            $ref: '#/components/schemas/FarmingInfo'
        chain:
          type: string
          enum:
            - SUI
          example: SUI
        type:
          type: string
          enum:
            - AMM
          example: AMM
        meta:
          type: object
          properties:
            protocol:
              $ref: '#/components/schemas/ProtocolMeta'
    CLMMPosition:
      type: object
      properties:
        positionId:
          type: string
          example: '0x4f551b64b0a7df43626ac93962c4eb67a58c29b0336ce166c739aee0bd717ddc'
        poolId:
          type: string
          example: '0xddeb2c1c4a5794623105c5c2f6b4c59018036cf914181e910e46dfb0fbe31326'
        poolName:
          type: string
          example: SUI-USDC
        owner:
          type: string
          example: '0x692853c81afc8f847147c8a8b4368dc894697fc12b929ef3071482d27339815e'
        input:
          type: array
          items:
            $ref: '#/components/schemas/TokenPosition'
        yieldCollected:
          type: array
          items:
            $ref: '#/components/schemas/TokenPosition'
        current:
          type: object
          properties:
            tokens:
              type: array
              items:
                $ref: '#/components/schemas/TokenPosition'
            currentPrice:
              type: number
              example: 1504.79
            lowerPrice:
              type: number
              example: 1105.12
            upperPrice:
              type: number
              example: 1624.82
            isInRange:
              type: boolean
              example: true
            yield:
              type: array
              items:
                $ref: '#/components/schemas/TokenPosition'
        chain:
          type: string
          enum:
            - SUI
          example: SUI
        type:
          type: string
          enum:
            - CLMM
          example: CLMM
        farming:
          type: array
          items:
            $ref: '#/components/schemas/FarmingInfo'
        meta:
          type: object
          properties:
            protocol:
              $ref: '#/components/schemas/ProtocolMeta'
        isFullRange:
          type: boolean
          example: false
    DLMMPosition:
      type: object
      properties:
        positionId:
          type: string
          example: '0x4f551b64b0a7df43626ac93962c4eb67a58c29b0336ce166c739aee0bd717ddc'
        poolId:
          type: string
          example: '0xddeb2c1c4a5794623105c5c2f6b4c59018036cf914181e910e46dfb0fbe31326'
        owner:
          type: string
          example: '0x692853c81afc8f847147c8a8b4368dc894697fc12b929ef3071482d27339815e'
        input:
          type: array
          items:
            $ref: '#/components/schemas/TokenPosition'
        yieldCollected:
          type: array
          items:
            $ref: '#/components/schemas/TokenPosition'
        current:
          type: object
          properties:
            tokens:
              type: array
              items:
                $ref: '#/components/schemas/TokenPosition'
            currentPrice:
              type: number
              example: 1504.79
            lowerPrice:
              type: number
              example: 1105.12
            upperPrice:
              type: number
              example: 1624.82
            numBins:
              type: number
              example: 10
              description: Number of bins in the DLMM position
            isInRange:
              type: boolean
              example: true
            yield:
              type: array
              items:
                $ref: '#/components/schemas/TokenPosition'
        base_fee_rate:
          type: string
          example: '10000000'
          description: Base fee rate for the DLMM position in bps
        chain:
          type: string
          enum:
            - SUI
          example: SUI
        type:
          type: string
          enum:
            - DLMM
          example: DLMM
        tags:
          type: array
          items:
            type: string
          example:
            - 0.01%
        meta:
          type: object
          properties:
            protocol:
              $ref: '#/components/schemas/ProtocolMeta'
    BorrowPosition:
      type: object
      properties:
        positionId:
          type: string
          example: '0x91bd1dc1cc5586706444ab8f7f9b2bf3f73e97aabb3269e03291763ed5fc4262'
        owner:
          type: string
          example: '0x7383b5e076553f79822374baca843c8fac02d510fb0f4ab344fc7ab591be94a7'
        poolId:
          type: string
          example: 0x123...abc
        input:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/TokenPosition'
              - $ref: '#/components/schemas/LendingPosition'
        yieldCollected:
          type: array
          items:
            $ref: '#/components/schemas/TokenPosition'
        current:
          type: object
          properties:
            tokens:
              type: array
              items:
                $ref: '#/components/schemas/TokenPosition'
            yield:
              type: array
              items:
                $ref: '#/components/schemas/TokenPosition'
            healthy:
              type: number
              example: 1.5
        fee:
          type: object
          properties:
            value:
              type: number
              example: 0
        chain:
          type: string
          example: SUI
        type:
          type: string
          enum:
            - Borrow
          example: Borrow
        tags:
          type: array
          items:
            type: string
          example:
            - Boosted
        farming:
          type: array
          items:
            $ref: '#/components/schemas/FarmingInfo'
        meta:
          type: object
          properties:
            protocol:
              $ref: '#/components/schemas/ProtocolMeta'
    FarmPosition:
      type: object
      properties:
        positionId:
          type: string
          example: '0x91bd1dc1cc5586706444ab8f7f9b2bf3f73e97aabb3269e03291763ed5fc4262'
        poolId:
          type: string
          example: 0x123...abc
        type:
          type: string
          enum:
            - Farm
          example: Farm
        owner:
          type: string
          example: '0x7383b5e076553f79822374baca843c8fac02d510fb0f4ab344fc7ab591be94a7'
        input:
          type: array
          items:
            $ref: '#/components/schemas/TokenPosition'
        claimed:
          type: array
          items:
            $ref: '#/components/schemas/TokenPosition'
        current:
          type: object
          properties:
            tokens:
              type: array
              items:
                $ref: '#/components/schemas/TokenPosition'
            yield:
              type: array
              items:
                $ref: '#/components/schemas/TokenPosition'
            fee:
              type: object
              properties:
                amount:
                  type: number
                  example: 0
                token:
                  $ref: '#/components/schemas/TokenInfo'
            healthy:
              type: number
              example: 1.5
        tags:
          type: array
          items:
            type: string
          example:
            - Boosted
        chain:
          type: string
          example: SUI
        meta:
          type: object
          properties:
            protocol:
              $ref: '#/components/schemas/ProtocolMeta'
    PerpPosition:
      type: object
      properties:
        positionId:
          type: string
          example: '0x19ef99a7dca285f613b2c6ced29d5e4f29e72670f869ac59ae25032f33e57bb3'
        owner:
          type: string
          example: '0x692853c81afc8f847147c8a8b4368dc894697fc12b929ef3071482d27339815e'
        input:
          type: array
          items:
            $ref: '#/components/schemas/TokenPosition'
        current:
          type: object
          properties:
            tokens:
              type: array
              items:
                $ref: '#/components/schemas/TokenPosition'
            yield:
              type: array
              items:
                $ref: '#/components/schemas/TokenPosition'
            side:
              type: string
              enum:
                - long
                - short
            indexToken:
              $ref: '#/components/schemas/TokenPosition'
            size:
              type: number
            notional:
              type: number
            leverage:
              type: number
            entryPrice:
              type: number
            markPrice:
              type: number
            liquidationPrice:
              type: number
            unrealizedPnl:
              type: number
        fee:
          type: number
          example: 0
        chain:
          type: string
          example: SUI
        type:
          type: string
          enum:
            - Perp
          example: Perp
        meta:
          type: object
          properties:
            protocol:
              $ref: '#/components/schemas/ProtocolMeta'
    MarginPosition:
      type: object
      properties:
        positionId:
          type: string
        owner:
          type: string
        input:
          type: array
          items:
            $ref: '#/components/schemas/TokenPosition'
        current:
          type: object
          properties:
            tokens:
              type: array
              items:
                $ref: '#/components/schemas/TokenPosition'
            debt:
              type: array
              items:
                $ref: '#/components/schemas/TokenPosition'
            yield:
              type: array
              items:
                $ref: '#/components/schemas/TokenPosition'
            side:
              type: string
              enum:
                - long
                - short
            leverage:
              type: number
            netValue:
              type: number
            liquidationPrice:
              type: number
            healthy:
              type: number
            borrowApr:
              type: number
        fee:
          type: number
          example: 0
        chain:
          type: string
          example: SUI
        type:
          type: string
          enum:
            - Margin
          example: Margin
        meta:
          type: object
          properties:
            protocol:
              $ref: '#/components/schemas/ProtocolMeta'
    TokenPosition:
      type: object
      required:
        - amount
        - value
        - token
      properties:
        amount:
          type: number
          example: 230.1003476015875
        value:
          type: number
          example: 89.34665515948616
        token:
          $ref: '#/components/schemas/TokenInfo'
    FarmingInfo:
      type: object
      properties:
        base_apr:
          type: number
          example: 10
        rewards_apr:
          type: number
          example: 20
        total_apr:
          type: number
          example: 30
        total_apy:
          type: number
          example: 40
        rewards:
          nullable: true
          type: array
          items:
            type: object
            properties:
              token_address:
                type: string
                example: >-
                  0x7016aae72cfc67f2fadf55769c0a7dd54291a583b63051a5ed71081cce836ac6::sca::SCA
              logo:
                type: string
                nullable: true
                example: >-
                  https://token-logo.getnimbus.io/api/v1/logo?address=0x7016...&chain=SUI
              token_name:
                type: string
                example: Scallop
              token_symbol:
                type: string
                example: SCA
              token_decimals:
                type: number
                example: 9
    ProtocolMeta:
      type: object
      properties:
        name:
          type: string
          example: Scallop
        logo:
          type: string
          example: https://strapi-dev.scand.app/uploads/Scallop_e86ded6cf4.jpg
        url:
          type: string
          example: https://scallop.io/
        protocol:
          type: string
          example: Scallop
    TokenInfo:
      type: object
      required:
        - contract_address
        - decimals
        - name
        - symbol
        - logo
      properties:
        contract_address:
          type: string
          example: >-
            0x7016aae72cfc67f2fadf55769c0a7dd54291a583b63051a5ed71081cce836ac6::sca::SCA
        timestamp:
          type: number
          example: 1732681440
        price:
          type: number
          example: 0.38829430763915
        last24hPrice:
          type: number
          example: 0.2
        poolId:
          type: string
          example: >-
            lending:0x83556891f4a0f233ce7b05cfe7f957d4020492a34f5405b2cb9377d060bef4bf::spring_sui::SPRING_SUI
        decimals:
          type: number
          example: 9
        name:
          type: string
          example: Scallop
        symbol:
          type: string
          example: SCA
        source:
          type: string
          example: Nimbus
        logo:
          type: string
          nullable: true
          example: >-
            https://token-logo.getnimbus.io/api/v1/logo?address=0x7016...&chain=SUI
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for authentication
      x-default: nimbus-6a7c85b1-99f4-4d99-b8f3-e6e49b8daad0

````