Documentation Index Fetch the complete documentation index at: https://docs.txshield.xyz/llms.txt
Use this file to discover all available pages before exploring further.
Overview Most honeypot detectors only check a token at the current moment.
TxShield’s honeypot endpoint runs time-travel analysis — simulating
the token’s behavior across three future time windows to catch traps that
activate after launch.
A token can show 0% tax right now and 99% sell tax 24 hours later.
That’s a time-delayed honeypot, and standard checks miss it entirely.
Endpoint POST/api/honeypot/honeypot-checksRequest Content-Type: application/json Authorization: Bearer txs_your_api_key_here
Body { "targetContractAddress" : "0x3e391e5cb8ea766c93134faf486e6393158032c2" , "chainId" : 1 }
Parameters Field Type Required Description targetContractAddressstring✅ The token contract address to analyze chainIdnumber✅ Chain to run the check on. See supported IDs below
Supported Chain IDs Chain chainId Ethereum 1BNB Smart Chain 56Base 8453Arbitrum 42161
Response { "success" : true , "honeypotResponse" : { "riskScore" : 0 , "buyTax" : 0 , "sellTax" : 0 , "isTimeHoneypot" : false , "errorReason" : "" , "timeTravelResults" : [ { "label" : "Immediate" , "isBlackListDetected" : false , "isMintable" : false , "mintScore" : 0 , "mintReason" : "" , "isTradingControl" : false , "buyTax" : 0 , "sellTax" : 0 , "riskScore" : 0 , "errorReason" : "" }, { "label" : "24 Hours" , "isBlackListDetected" : false , "isMintable" : false , "mintScore" : 0 , "mintReason" : "" , "isTradingControl" : false , "buyTax" : 0 , "sellTax" : 0 , "riskScore" : 0 , "errorReason" : "" }, { "label" : "7 Days" , "isBlackListDetected" : false , "isMintable" : false , "mintScore" : 0 , "mintReason" : "" , "isTradingControl" : false , "buyTax" : 0 , "sellTax" : 0 , "riskScore" : 0 , "errorReason" : "" } ] } }
Response Fields Explained Top Level Field Type Description successbooleanWhether the request succeeded honeypotResponseobjectContainer for all honeypot analysis data
honeypotResponseField Type Description riskScorenumberOverall risk score from 0 to 100. Above 70 is high risk buyTaxnumberCurrent buy tax percentage sellTaxnumberCurrent sell tax percentage isTimeHoneypotbooleantrue if tax or risk increases across time windows — the key flagerrorReasonstringPopulated when analysis partially fails or detects a specific trap timeTravelResultsarrayAnalysis results across three simulated time windows
timeTravelResults[] — Each Time WindowField Type Description labelstringTime window: "Immediate", "24 Hours", or "7 Days" buyTaxnumberBuy tax at this simulated time sellTaxnumberSell tax at this simulated time riskScorenumberRisk score at this simulated time isBlackListDetectedbooleanWhether blacklist functionality was detected at this window isMintablebooleanWhether the contract can mint new tokens at this window mintScorenumberConfidence score for mint risk. Higher = more dangerous mintReasonstringExplanation if mint risk is detected isTradingControlbooleanWhether the owner can pause or restrict trading at this window errorReasonstringSpecific error or finding for this time window
How to Read the Results The Safe Token { "riskScore" : 0 , "buyTax" : 0 , "sellTax" : 0 , "isTimeHoneypot" : false , "timeTravelResults" : [ { "label" : "Immediate" , "buyTax" : 0 , "sellTax" : 0 , "riskScore" : 0 }, { "label" : "24 Hours" , "buyTax" : 0 , "sellTax" : 0 , "riskScore" : 0 }, { "label" : "7 Days" , "buyTax" : 0 , "sellTax" : 0 , "riskScore" : 0 } ] }
All three windows consistent. No flags. Safe to proceed.
The Time-Delayed Honeypot { "riskScore" : 92 , "buyTax" : 3 , "sellTax" : 15 , "isTimeHoneypot" : true , "errorReason" : "Tax spikes dramatically after 24 hours" , "timeTravelResults" : [ { "label" : "Immediate" , "buyTax" : 3 , "sellTax" : 15 , "riskScore" : 45 }, { "label" : "24 Hours" , "buyTax" : 3 , "sellTax" : 99 , "riskScore" : 100 }, { "label" : "7 Days" , "buyTax" : 3 , "sellTax" : 99 , "riskScore" : 100 } ] }
Looks tradeable right now. By 24 hours, sell tax hits 99% —
users are trapped. isTimeHoneypot: true is your block signal.
The Blacklist Trap { "riskScore" : 75 , "buyTax" : 5 , "sellTax" : 5 , "isTimeHoneypot" : false , "timeTravelResults" : [ { "label" : "Immediate" , "isBlackListDetected" : false , "riskScore" : 20 }, { "label" : "24 Hours" , "isBlackListDetected" : true , "riskScore" : 75 }, { "label" : "7 Days" , "isBlackListDetected" : true , "riskScore" : 75 } ] }
Tax looks fine. But blacklist activates at 24 hours —
owner can block any wallet from selling at any time.
Risk Score Reference Score Verdict Recommended Action 0 – 20Safe Proceed normally 21 – 50Low Risk Proceed with caution 51 – 70Medium Risk Warn user, show flags 71 – 90High Risk Strong warning, require confirmation 91 – 100Critical Risk Block the transaction
Always check isTimeHoneypot alongside riskScore. A token can have a
moderate score at the "Immediate" window but become Critical Risk by
"7 Days". The time-travel delta is the most important signal.
Code Examples curl -X POST https://api.txshield.xyz/api/honeypot/honeypot-checks \ -H "Content-Type: application/json" \ -H "Authorization: Bearer txs_your_api_key_here" \ -d '{ "targetContractAddress": "0x3e391e5cb8ea766c93134faf486e6393158032c2", "chainId": 1 }'
Error Responses Status Error Meaning 400targetContractAddress is requiredMissing address in body 400chainId is requiredMissing chainId in body 401Missing Authorization headerNo API key provided 403Invalid API keyKey not found or revoked 429Analysis rate limit hitExceeded 10 req/min 500Honeypot check failedInternal error or RPC failure
EVM Simulation Run a full simulation with bytecode analysis alongside honeypot detection.
Authentication How to generate and use your API key.
