> For the complete documentation index, see [llms.txt](https://docs.definest.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.definest.ai/api/wallet-analytics/wallet-deals.md).

# 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"}}}}}}
```