Verify Attribution

Confirm that a transaction carries valid Turtle tracking data for your distributor

Requires an API key via the X-API-Key header. See API Keys.

Overview

GET /v2/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 attribution metadata (including distributorId, opportunityId, the deposited amount, 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

curl -X GET "https://earn.turtle.xyz/v2/actions/verify?chainId=1&txHash=0xedfdf71e..." \
  -H "X-API-Key: pk_live_xxxxx"

const params = new URLSearchParams({
  chainId: '1',
  txHash: '0xedfdf71e0e4daec5afcb87988821a8bccd5c282647c8e81a65a71181a44a8e51',
});

const response = await fetch(
  `https://earn.turtle.xyz/v2/actions/verify?${params}`,
  { headers: { 'X-API-Key': 'pk_live_xxxxx' } }
);
const data = await response.json();

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": {
    "action": "deposit",
    "actionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "amount": "1000000",
    "amountUsd": "1.00",
    "distributorId": "dist123",
    "opportunityId": "550e8400-e29b-41d4-a716-446655440000",
    "referralCode": "ref456",
    "tokenIn": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "tokenInDecimals": 6
  },
  "signatureValid": true
}

tag · string

The raw tracking tag found in the transaction data.

metadata · object

Parsed attribution metadata for the transaction.

Show metadata

action · string

The attributed action type (e.g., deposit).

actionId · string

The action ID associated with the attributed transaction.

amount · string

The deposited amount in the input token’s smallest unit.

amountUsd · string

The deposited amount in USD.

distributorId · string

The distributor the transaction is attributed to.

opportunityId · string

The opportunity the deposit was made into.

referralCode · string

The referral code embedded in the tracking data, if present.

tokenIn · string

The address of the input token.

tokenInDecimals · integer

The decimals of the input token.

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

Malformed txHash or chainId

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.

No tracking data found

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.

Invalid signature

Status: 200 OK

{
  "tag": "turtle:v1:dist123:ref456",
  "metadata": {
    "action": "deposit",
    "actionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "amount": "1000000",
    "amountUsd": "1.00",
    "distributorId": "dist123",
    "opportunityId": "550e8400-e29b-41d4-a716-446655440000",
    "referralCode": "ref456",
    "tokenIn": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "tokenInDecimals": 6
  },
  "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.

Related

• Deposit: Generate the deposit whose attribution you are verifying
• Distributor Activity: List every deposit attributed to your distributor
• Distributor Model: How attribution and revenue tracking work