> 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/copy-trade-simulator.md).

# Copy Trade Simulator

## POST /wallets/simulator

> Simulate wallets copy trading results

```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"}},"schemas":{"Wallet":{"properties":{"address":{"type":"string","description":"Wallet address"}}},"BlockchainNetwork":{"type":"string","enum":["eth","sol"],"description":"Supported blockchain networks"},"PnlValue":{"type":["number"],"description":"PNL value in USD ($)"},"RoiValue":{"type":["number"],"description":"ROI value in percent (%)"},"TradingVolumeValue":{"type":["number"],"description":"Trading volume value in USD ($)"},"InvestmentAmountValue":{"type":["number"],"description":"Investment amount value in USD ($)"},"ChartTimestampsArray":{"type":"array","description":"Array of timestamps for each data point","items":{"type":["integer"],"description":"UNIX timestamp in seconds"}},"SimulatedDeal":{"type":"object","description":"Simulated deal information","properties":{"open_time":{"type":["integer"],"description":"Opening time. Timestamp in seconds"},"last_operation_time":{"type":["integer"],"description":"Last operation time. Timestamp in seconds"},"status":{"type":["string"],"enum":["open","closed"]},"token":{"type":"object","description":"Token information","properties":{"name":{"$ref":"#/components/schemas/Token/properties/name"},"symbol":{"$ref":"#/components/schemas/Token/properties/symbol"},"address":{"$ref":"#/components/schemas/Token/properties/address"}},"required":["name","symbol","address"]},"pnl_realized":{"$ref":"#/components/schemas/PnlValue"},"pnl_unrealized":{"$ref":"#/components/schemas/PnlValue"},"pnl_total":{"$ref":"#/components/schemas/PnlValue"},"roi_realized":{"$ref":"#/components/schemas/RoiValue"},"roi_total":{"$ref":"#/components/schemas/RoiValue"},"usd_slippage_loss":{"type":["number"],"description":"Slippage loss in USD ($)"},"usd_network_fee":{"type":["number"],"description":"Network fee in USD ($)"},"usd_bot_fee":{"type":["number"],"description":"Bot fee in USD ($)"},"investment_amount":{"$ref":"#/components/schemas/InvestmentAmountValue"},"trades_number":{"type":["integer"],"description":"Number of trades in deal"},"closed_position":{"type":["number","integer"],"description":"Close position percent (%)"},"special_tag":{"type":["string","null"],"enum":["sell_timefix_final","sell_timefix","close_all"],"description":"Special tag.\n`sell_timefix_final` - closed by final timefix operation\n`sell_timefix` - closed by timefix operation in the middle of deal\n`close_all` - closed by close_all setting\n"},"trades":{"type":"array","description":"Array of simulated trade operations","items":{"$ref":"#/components/schemas/SimulatedTrade"}}},"required":["open_time","last_operation_time","status","token","pnl_realized","pnl_unrealized","pnl_total","roi_realized","roi_total","roi_total","usd_slippage_loss","usd_network_fee","usd_bot_fee","investment_amount","trades_number","closed_position","special_tag","trades"]},"Token":{"properties":{"name":{"type":["string","null"],"description":"Token name"},"symbol":{"type":["string","null"],"description":"Token symbol"},"address":{"type":["string"],"description":"Token address"}}},"SimulatedTrade":{"type":"object","description":"Simulated trade operation","properties":{"type":{"type":["string"],"description":"Operation type. \n`buy` - basic buy operation\n`sell` - basic sell operation\n`sell_timefix` - Time fix sell operation in the middle of deal\n`sell_timefix_final` - Time fix sell operation in the end of deal\n","enum":["buy","sell","sell_timefix","sell_timefix_final"]},"time":{"$ref":"#/components/schemas/Trade/properties/time"},"usd_amount":{"$ref":"#/components/schemas/Trade/properties/usd_amount"},"quantity":{"$ref":"#/components/schemas/Trade/properties/quantity"},"usd_price":{"$ref":"#/components/schemas/Trade/properties/usd_price"},"usd_liquidity":{"$ref":"#/components/schemas/Trade/properties/usd_liquidity"},"usd_buy_price_avg":{"type":["number"],"description":"Current average purchase price in USD ($)"},"usd_invested":{"type":["number"],"description":"Current invested amount in USD ($)"},"slippage":{"type":["number"],"description":"Slippage percent (%)"},"usd_network_fee":{"$ref":"#/components/schemas/Trade/properties/network_fee/properties/usd"},"usd_bot_fee":{"type":["number"],"description":"Bot fee in USD ($)"}},"required":["type","time","usd_amount","quantity","usd_price","usd_liquidity","usd_buy_price_avg","usd_invested","slippage","usd_network_fee","usd_bot_fee"]},"Trade":{"properties":{"time":{"type":["integer"],"description":"Time of trade operation. Timestamp in seconds"},"usd_amount":{"type":["number","null"],"description":"Trade amount in USD ($)"},"quantity":{"type":["number"],"description":"Trade token amount"},"usd_price":{"type":["number","null"],"description":"Trade price in USD ($)"},"usd_liquidity":{"type":["number","null"],"description":"Trade token liquidity in USD ($)"},"network_fee":{"properties":{"usd":{"type":["number"],"description":"Network fee amount in USD ($)"}}}}}},"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/simulator":{"post":{"tags":["wallet"],"description":"Simulate wallets copy trading results","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Simulation input data","properties":{"wallets":{"type":"array","description":"List of wallets to follow","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/Wallet/properties/address"}},"network":{"$ref":"#/components/schemas/BlockchainNetwork"},"from_date":{"type":["string"],"description":"Time interval start date. UTC timezone. YYYY-MM-DD format"},"to_date":{"type":["string"],"description":"Time interval end date. UTC timezone. YYYY-MM-DD format"},"buy_percentage":{"type":["integer"],"description":"Copy trading buy percentage (%)","exclusiveMinimum":0},"max_buy_amount":{"type":["number"],"description":"Maximum purchase amount, in USD ($)","exclusiveMinimum":0},"max_position_amount":{"type":["number"],"description":"Maximum position amount per deal, in USD ($)","exclusiveMinimum":0},"priority_fee":{"type":["number"],"description":"Priority fee amount, in network native currency","minimum":0},"bribe":{"type":["number"],"description":"Bribe amount, in network native currency","minimum":0},"max_dupe_buy_times":{"type":["integer"],"description":"Maximum number of additional purchases","minimum":0},"close_all":{"type":["boolean"],"description":"Close deal on first sell","default":false},"inactivity_time_fix":{"type":["null","object"],"description":"Setting for automatic deal closure when there is no activity\n","default":null,"properties":{"hours":{"type":["integer"],"minimum":1,"maximum":192,"description":"Number of hours of inactivity"}},"required":["hours"]},"include_bot_fees":{"type":["boolean"],"description":"Include fees in calculations","default":false}},"required":["wallets","network","from_date","to_date","buy_percentage","max_buy_amount","max_position_amount","priority_fee","bribe","max_dupe_buy_times"]}}}},"responses":{"200":{"description":"Simulation result","content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"object","description":"Wallets indicators summary","properties":{"pnl_total":{"$ref":"#/components/schemas/PnlValue"},"pnl_realized":{"$ref":"#/components/schemas/PnlValue"},"pnl_unrealized":{"$ref":"#/components/schemas/PnlValue"},"roi_total":{"$ref":"#/components/schemas/RoiValue"},"roi_realized":{"$ref":"#/components/schemas/RoiValue"},"bot_fees":{"type":["number"],"description":"Bot fees in USD ($)"},"network_fees":{"type":["number"],"description":"Network fees in USD ($)"},"linearity_r2_closed_deals":{"type":["number"],"description":"Linearity R2 (Closed Deals)"},"top_deal_dominance":{"type":["number"],"description":"Top Deal Dominance. In percent (%)"},"trading_volume":{"$ref":"#/components/schemas/TradingVolumeValue"},"slippage_loss":{"type":["number"],"description":"Slippage Loss in USD ($)"},"investment_amount":{"$ref":"#/components/schemas/InvestmentAmountValue"},"investment_amount_closed_deals":{"$ref":"#/components/schemas/InvestmentAmountValue"},"investment_amount_open_deals":{"$ref":"#/components/schemas/InvestmentAmountValue"}},"required":["pnl_total","pnl_realized","pnl_unrealized","roi_total","roi_realized","bot_fees","network_fees","linearity_r2_closed_deals","top_deal_dominance","trading_volume","slippage_loss","investment_amount","investment_amount_closed_deals","investment_amount_open_deals"]},"cumulative_pnl_and_fee_chart":{"type":"object","description":"Cumulative PnL and Fees chart","properties":{"pnl_realized":{"type":"array","description":"Array of realized PNL values for each data point","items":{"$ref":"#/components/schemas/PnlValue"}},"pnl_unrealized":{"type":"array","description":"Array of unrealized PNL values for each data point","items":{"$ref":"#/components/schemas/PnlValue"}},"pnl_total":{"type":"array","description":"Array of total PNL values for each data point","items":{"$ref":"#/components/schemas/PnlValue"}},"fee_sum":{"type":"array","description":"Array of fee sum values for each data point","items":{"type":"number","description":"Fee sum value in USD ($)"}},"bot_fee":{"type":"array","description":"Array of bot fee values for each data point","items":{"type":"number","description":"Bot fee value in USD ($)"}},"deal_indexes":{"type":"array","description":"Array of deal index for each data point","items":{"type":["integer"],"description":"Deal index"}},"timestamps":{"$ref":"#/components/schemas/ChartTimestampsArray"}},"required":["pnl_realized","pnl_unrealized","pnl_total","fee_sum","bot_fee","deal_indexes","timestamps"]},"cumulative_usd_closed_deals_chart":{"type":"object","description":"Cumulative USD for closed deals chart","properties":{"values":{"type":"array","description":"Array of USD ($) values corresponding to each timestamp","items":{"type":["integer"],"description":"USD ($) value at the given timestamp"}},"timestamps":{"$ref":"#/components/schemas/ChartTimestampsArray"}},"required":["values","timestamps"]},"cumulative_usd_open_deals_chart":{"type":"object","description":"Cumulative USD for still open deals chart","properties":{"values":{"type":"array","description":"Array of USD ($) values corresponding to each timestamp","items":{"type":["integer"],"description":"USD ($) value at the given timestamp"}},"timestamps":{"$ref":"#/components/schemas/ChartTimestampsArray"}},"required":["values","timestamps"]},"deals":{"type":"array","description":"Array of deals","items":{"$ref":"#/components/schemas/SimulatedDeal"}}},"required":["summary","cumulative_pnl_and_fee_chart","cumulative_usd_closed_deals_chart","cumulative_usd_open_deals_chart","deals"]}}}},"400":{"$ref":"#/components/responses/400BadRequest"},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"}}}}}}
```