Skip to main content
Requires an API key via the X-API-Key header. See API Keys.

​
Overview

GET /v1/actions/verify Check whether a transaction carries valid Turtle tracking data. Pass a transaction hash and chain ID, and the endpoint returns the tracking tag, the parsed distributorId and referralCode, and whether the signature is from Turtle’s attribution wallet. Use it to confirm attribution independently, or for debugging. This works for any attributed deposit, however it was generated. A deposit built through Deposit and a no-code share-link deposit both embed the same tracking signature, so both verify the same way. 
curl -X GET "https://earn.turtle.xyz/v1/actions/verify?chainId=1&txHash=0xedfdf71e..." \
  -H "X-API-Key: pk_live_xxxxx"
Query Parameters
​
chainId
integer
required
The chain ID where the transaction was executed (e.g., 1 for Ethereum, 42161 for Arbitrum).
​
txHash
string
required
The transaction hash to verify (0x followed by 64 hex characters).
Response 
{
  "tag": "turtle:v1:dist123:ref456",
  "metadata": {
    "distributorId": "dist123",
    "referralCode": "ref456"
  },
  "signatureValid": true
}
​
tag
string
The raw tracking tag found in the transaction data.
​
metadata
object
Parsed tracking metadata containing distributorId and optionally referralCode.
​
signatureValid
boolean
required
Whether the tracking signature is from Turtle’s attribution wallet.
​
error
string
Error message if verification failed (e.g., no tracking data found).

​
Error Handling

Status: 400 Bad Request
{
  "error": "invalid_request",
  "message": "Invalid txHash or chainId"
}
Solution: Pass a chainId integer for a supported chain and a txHash of 0x followed by 64 hex characters.
Status: 404 Not Found
{
  "error": "tracking_data_not_found",
  "message": "No tracking data found in transaction"
}
Solution: Confirm the transaction is the attributed deposit and that it embedded a Turtle tracking signature. A plain transfer or a deposit built without a distributorId carries no tracking data.
Status: 200 OK
{
  "tag": "turtle:v1:dist123:ref456",
  "metadata": {
    "distributorId": "dist123",
    "referralCode": "ref456"
  },
  "signatureValid": false
}
Solution: A tracking tag is present but its signature is not from Turtle’s attribution wallet, so the deposit is not attributed. Rebuild the deposit through Deposit so the tracking signature is generated by Turtle.