> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turtle.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Distributor Model

> How Turtle scopes API calls to a distributor and attributes deposits automatically

Every Earn API call is scoped to a distributor. The distributor is what white-labels vault discovery, ties deposits back to your integration, and drives revenue share. This page is the canonical reference for that model. For the product-level story of who Turtle Earn is for and how the commercial relationship works, see the [Turtle Earn overview](/partner-products/turtle-earn).

## Video walkthrough

A quick recap of how anyone can become a distributor and use the API.

<Frame>
  <iframe width="560" height="315" src="https://www.loom.com/embed/763abc85dafa44edba72ef0689c2a7df" title="Turtle Distribution Tooling" frameborder="0" allow="fullscreen; picture-in-picture; clipboard-write" allowfullscreen />
</Frame>

## What is a distributor

A distributor is an integration point that embeds Turtle vault opportunities into a product. Each distributor has a unique `distributorId` that scopes endpoint responses to that integration and tags the deposits it generates.

## Distributor vs organization

An **organization** is the top-level entity that manages billing, team members, and settings. A **distributor** sits within an organization and represents one specific integration, with its own API keys, opportunity selection, and attribution tracking.

One organization can have multiple distributors. A wallet product might run one distributor for its mobile app and a separate one for web, each with a different opportunity set configured in the [Dashboard](https://dashboard.turtle.xyz).

## How attribution works

You never call an endpoint to record attribution. It happens on-chain, automatically, off the deposit you generate.

<Steps>
  <Step title="Tracking signature embedded">
    When you generate a deposit transaction with your `distributorId`, Turtle embeds that ID into the transaction calldata as a tracking signature.
  </Step>

  <Step title="On-chain detection">
    Turtle monitors the supported chains and detects transactions that carry a tracking signature.
  </Step>

  <Step title="Deposit attributed">
    The detected deposit is attributed to your distributor account. No manual call is required.
  </Step>
</Steps>

<Note>
  The `POST /v1/actions/attribute` endpoint has been removed. Attribution is fully automatic. There is no endpoint to call to record it.
</Note>

To confirm a specific transaction carries your tracking signature, use [Verify Attribution](/sdk/earn/verify-attribution). To pull the full list of deposits attributed to your distributor, use [Distributor Activity](/sdk/earn-api/deposits).

## Distributor-scoped opportunities

Each distributor has a set of opportunities configured in the [Dashboard](https://dashboard.turtle.xyz). Fetch only the opportunities enabled for your integration:

```bash theme={null}
GET /v2/opportunities/distributors/{distributorId}
```

This returns the same Opportunity objects as the full catalog, filtered to your selection, so users only see the vaults you have approved. See [Get Opportunities](/sdk/opportunities/get-opportunities) for the full object reference and the distributor-scoped endpoint.

## Share links

You can attribute deposits without any API integration. Append your `distributorId` to any opportunity URL as a query parameter:

```
https://app.turtle.xyz/earn/opportunities/{slug}?distId={your_distributor_id}
```

Deposits made through that link trigger the same on-chain attribution as an API-generated deposit. See [Share Links](/partner-products/share-links) for the no-code guide.

## Revenue share

Distributors earn a share of the yield generated by the users they onboard. Rates are configured per distributor in the [Dashboard](https://dashboard.turtle.xyz) and revenue is tracked off the deposits attributed to your `distributorId`. {/* VERIFY: are distributor revenue-share rates publishable in docs, or do they stay Dashboard-only? Source: KB earn-api.md flags rates as undocumented by design. */}