# Wallet deals

## GET /wallets/{address}/deals

> Returns wallet deals. \
> When the \`from\_time\` or \`to\_time\` fields are specified, \
> deals will be filtered and recalculated for the given time range.<br>

```json
{"openapi":"3.1.0","info":{"title":"Analytics API","version":"1.0.4"},"tags":[{"name":"wallet","description":"Wallet"}],"servers":[{"url":"https://definest.ai/api/analytics/v1","description":"Production server"}],"security":[{"xApiKey":[]}],"components":{"securitySchemes":{"xApiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key for authentication"}},"parameters":{"WalletAddressPathParam":{"name":"address","in":"path","description":"Wallet address","required":true,"schema":{"$ref":"#/components/schemas/Wallet/properties/address"}},"BlockchainNetworkQueryParam":{"name":"network","in":"query","description":"Blockchain network","required":true,"schema":{"$ref":"#/components/schemas/BlockchainNetwork"}},"FromTimeQueryParam":{"name":"from_time","in":"query","description":"Timestamp in seconds. \nMinimum time for the deal's first trade.\nDeals started before this time will be excluded from result and calculations.\n","schema":{"type":["integer","number"],"minimum":1}},"ToTimeQueryParam":{"name":"to_time","in":"query","description":"Timestamp in seconds. \nMaximum time for deal trades. \nTrades executed after this time will be excluded from result and calculations.\n","schema":{"type":["integer","number"],"minimum":1}}},"schemas":{"Wallet":{"properties":{"address":{"type":"string","description":"Wallet address"},"network":{"$ref":"#/components/schemas/BlockchainNetwork"}}},"BlockchainNetwork":{"type":"string","enum":["eth","sol"],"description":"Supported blockchain networks"},"Deal":{"type":"object","description":"Deal information","properties":{"id":{"type":["integer"],"description":"Deal ID"},"network":{"$ref":"#/components/schemas/Wallet/properties/network"},"token":{"$ref":"#/components/schemas/Token"},"open_time":{"type":"object","description":"Opening time","properties":{"initial":{"type":"integer","description":"Initial opening time. Timestamp in seconds"},"following":{"type":["integer","null"],"description":"Following opening time. Timestamp in seconds"}},"required":["initial","following"]},"last_operation_time":{"type":"object","description":"Last operation time","properties":{"initial":{"type":"integer","description":"Initial last operation time. Timestamp in seconds"},"following":{"type":["integer","null"],"description":"Following last operation time. Timestamp in seconds"}},"required":["initial","following"]},"status":{"type":"object","description":"Deal status values","properties":{"initial":{"$ref":"#/components/schemas/DealStatus"},"following":{"$ref":"#/components/schemas/DealStatus"}},"required":["initial","following"]},"trades_number":{"type":"object","description":"Number of trades in deal","properties":{"initial":{"type":["integer"],"description":"Initial trades number"},"following":{"type":["integer","null"],"description":"Following trades number"}},"required":["initial","following"]},"closed_position":{"type":"object","description":"Close position percent (%)","properties":{"initial":{"type":["integer"],"description":"Initial close position percent"},"following":{"type":["integer","null"],"description":"Following close position percent"}},"required":["initial","following"]},"pnl_realized":{"$ref":"#/components/schemas/IndicatorPnlValues"},"pnl_unrealized":{"$ref":"#/components/schemas/IndicatorPnlValues"},"pnl_total":{"$ref":"#/components/schemas/IndicatorPnlValues"},"roi_realized":{"$ref":"#/components/schemas/IndicatorRoiValues"},"roi_unrealized":{"$ref":"#/components/schemas/IndicatorRoiValues"},"roi_total":{"$ref":"#/components/schemas/IndicatorRoiValues"},"roi_low":{"$ref":"#/components/schemas/IndicatorRoiValues"},"roi_high":{"$ref":"#/components/schemas/IndicatorRoiValues"},"capital_required":{"$ref":"#/components/schemas/IndicatorCapitalRequiredValues"},"pools":{"type":"array","description":"Used pools","items":{"$ref":"#/components/schemas/Pool"}},"trades":{"type":"array","items":{"$ref":"#/components/schemas/Trade"}}},"required":["id","network","token","open_time","last_operation_time","status","trades_number","closed_position","pnl_realized","pnl_unrealized","pnl_total","roi_realized","roi_unrealized","roi_total","roi_low","roi_high","capital_required","pools","trades"]},"Token":{"type":"object","description":"Token information","properties":{"network":{"$ref":"#/components/schemas/BlockchainNetwork"},"address":{"type":["string"],"description":"Token address"},"name":{"type":["string","null"],"description":"Token name"},"symbol":{"type":["string","null"],"description":"Token symbol"},"scam_status":{"type":["string","null"],"description":"Scam check status","enum":["ok","scam","undefined","checking","check_fail"]},"created_at":{"type":"integer","description":"Token creation time. Timestamp in seconds."},"started_at":{"type":["integer","null"],"description":"Token trading start time (first swap). Timestamp in seconds."}},"required":["network","address","name","symbol","scam_status","created_at","started_at"]},"DealStatus":{"type":"string","description":"Deal status.\n`open` - Deal is open.\n`closed` - Deal is closed.\n`send_receive` - Deal has send or receive operations.\n`scam` - Deal is marked as a scam.\n`oversell` - More sold than bought.\n","enum":["open","closed","send_receive","scam","oversell"]},"IndicatorPnlValues":{"type":"object","description":"PNL indicator values","properties":{"initial":{"$ref":"#/components/schemas/PnlValue"},"following":{"oneOf":[{"$ref":"#/components/schemas/PnlValue"},{"type":"null"}]}},"required":["initial","following"]},"PnlValue":{"type":["number"],"description":"PNL value in USD ($)"},"IndicatorRoiValues":{"type":"object","description":"ROI indicator values","properties":{"initial":{"$ref":"#/components/schemas/RoiValue"},"following":{"oneOf":[{"$ref":"#/components/schemas/RoiValue"},{"type":"null"}]}},"required":["initial","following"]},"RoiValue":{"type":["number"],"description":"ROI value in percent (%)"},"IndicatorCapitalRequiredValues":{"type":"object","description":"Capital required indicator values.","properties":{"initial":{"$ref":"#/components/schemas/InvestmentAmountValue"},"following":{"oneOf":[{"$ref":"#/components/schemas/InvestmentAmountValue"},{"type":"null"}]}},"required":["initial","following"]},"InvestmentAmountValue":{"type":["number"],"description":"Investment amount value in USD ($)"},"Pool":{"type":"object","description":"DEX Liquidity pool","properties":{"type":{"type":["string"],"description":"Pool type"},"address":{"type":["string"],"description":"Pool address"},"name":{"type":["string","null"],"description":"Pool name"}},"required":["type","address","name"]},"Trade":{"type":"object","description":"Trade operation","properties":{"id":{"type":["integer"],"description":"Trade ID"},"is_following":{"type":"boolean","description":"Trade is calculated by following strategy"},"type":{"type":["string"],"description":"Trade type","enum":["buy","sell","approve"]},"transaction_hash":{"type":["string","null"]},"application":{"oneOf":[{"$ref":"#/components/schemas/RouterApplication"},{"type":"null"}]},"usd_amount":{"type":["number","null"],"description":"Trade amount in USD ($)"},"quantity":{"type":["number"],"description":"Trade token amount"},"quantity_unlimited":{"type":["boolean"],"description":"Unlimited token amount. For `approve` trades"},"usd_price":{"type":["number","null"],"description":"Trade price in USD ($)"},"usd_liquidity":{"type":["number","null"],"description":"Trade token liquidity in USD ($)"},"usd_market_cap":{"type":["number","null"],"description":"Trade token market cap in USD ($)"},"token_age":{"type":["number","null"],"description":"Amount of minutes passed from token trading start time"},"time":{"type":["integer"],"description":"Time of trade operation. Timestamp in seconds"},"pools":{"type":"array","description":"Used pools","items":{"$ref":"#/components/schemas/Pool"}},"coin_fee":{"type":"object","description":"Coin fee values","properties":{"amount":{"type":["number"],"description":"Coin fee amount"},"percent":{"type":["number"],"description":"Coin fee percent (%)"}},"required":["amount","percent"]},"router_fee":{"type":"object","description":"Router fee values","properties":{"usd":{"type":["number"],"description":"Router fee amount in USD ($)"},"native":{"type":["number"],"description":"Router fee amount in native currency"}},"required":["usd","native"]},"network_fee":{"type":"object","description":"Network fee values","properties":{"usd":{"type":["number"],"description":"Network fee amount in USD ($)"},"native":{"type":["number"],"description":"Network fee amount in native currency"}},"required":["usd","native"]},"swaps":{"type":"array","description":"List of executed swaps","items":{"type":"object","description":"Swap information","properties":{"from":{"type":"object","description":"Send swap data","properties":{"amount":{"type":"number","description":"Sent token amount"},"symbol":{"$ref":"#/components/schemas/Token/properties/symbol"},"address":{"$ref":"#/components/schemas/Token/properties/address"}},"required":["amount","symbol","address"]},"to":{"type":"object","description":"Receive swap data","properties":{"amount":{"type":["number"],"description":"Received token amount"},"symbol":{"$ref":"#/components/schemas/Token/properties/symbol"},"address":{"$ref":"#/components/schemas/Token/properties/address"}},"required":["amount","symbol","address"]},"pool":{"oneOf":[{"$ref":"#/components/schemas/Pool"},{"type":"null"}]},"usd_price":{"type":["number","null"],"description":"Exchange price in USD ($)"}},"required":["from","to","pool","usd_price"]}}},"required":["id","is_following","type","transaction_hash","application","usd_amount","quantity","quantity_unlimited","usd_price","usd_liquidity","usd_market_cap","token_age","time","pools","coin_fee","router_fee","network_fee","swaps"]},"RouterApplication":{"type":"object","description":"Router application information","properties":{"name":{"type":["string","null"]},"address":{"type":["string"]}},"required":["name","address"]},"PagePagination":{"type":"object","properties":{"current":{"type":"integer","description":"Current page number"},"per_page":{"type":"integer","description":"Number of items per page"},"total_pages":{"type":"integer","description":"Total number of pages"},"total_items":{"type":"integer","description":"Total number of items"}},"required":["current","per_page"]},"ResponseCredits":{"type":"object","description":"Credits data after request","properties":{"spent":{"type":"integer","description":"Credits spent on the request"},"remaining":{"type":"integer","description":"Remaining credits"}},"required":["spent","remaining"]}},"responses":{"400BadRequest":{"description":"Request fail","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Error short code"},"detail":{"description":"Detailed error description"}},"required":["code"]}}}},"401Unauthorized":{"description":"API Key invalid or missing"},"403Forbidden":{"description":"API access forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Error short code"},"detail":{"description":"Detailed error description"}},"required":["code"]}}}}}},"paths":{"/wallets/{address}/deals":{"get":{"description":"Returns wallet deals. \nWhen the `from_time` or `to_time` fields are specified, \ndeals will be filtered and recalculated for the given time range.\n","tags":["wallet"],"parameters":[{"$ref":"#/components/parameters/WalletAddressPathParam"},{"$ref":"#/components/parameters/BlockchainNetworkQueryParam"},{"name":"page","in":"query","description":"Page number for pagination","schema":{"type":["integer"],"minimum":1,"default":1}},{"name":"per_page","in":"query","description":"Number of items to return per page","schema":{"type":["integer"],"minimum":1,"maximum":150,"default":30}},{"name":"search","in":"query","description":"Search string.\nSearches by partial token name, complete symbol, or full token address. Case-insensitive.\n","schema":{"type":["string"],"maxLength":128}},{"$ref":"#/components/parameters/FromTimeQueryParam"},{"$ref":"#/components/parameters/ToTimeQueryParam"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"object","properties":{"deals":{"type":"array","description":"List of deals","items":{"$ref":"#/components/schemas/Deal"}},"page":{"$ref":"#/components/schemas/PagePagination"}},"required":["deals","page"]},"credits":{"$ref":"#/components/schemas/ResponseCredits"}},"required":["result","credits"]}}}},"400":{"$ref":"#/components/responses/400BadRequest"},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.definest.ai/api/wallet-analytics/wallet-deals.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.