---
title: "GET /v2/social/traders"
method: GET
path: "/v2/social/traders"
tags: ["Social Activity"]
---

# GET /v2/social/traders

`GET /v2/social/traders`

## Request

- Base URL: `https://api.arbital.xyz` (the document declares no server; this is the origin it was published from)
- URL: `https://api.arbital.xyz/v2/social/traders`
- Auth: HTTP bearer

Without mode, legacy search requires query and supports limit 1-20; its 200 items shape is unchanged. mode selects a Fomo-only discovery page: new = Recently discovered by Arbital, for_you = Suggested traders, top_returns = Top traders. Suggested traders and Top traders retain the Fomo seven-day provider ranking within its top 100 candidates; Suggested traders excludes watched and dismissed profiles. No ML scoring or comparable thirty-day return ranking is claimed. Recently discovered uses the Indexer first-discovery clock, not account creation time, with no age cutoff. Omit period for new. The other modes default to 7d and accept explicit period=7d. Explicit period=30d, any period with new, missing discovery configuration or an unavailable Indexer recent-profile capability returns 501 trader_discovery_unsupported without retry instructions; thirty-day requests are never silently replaced with seven-day data. Transient source/admission failures return 503 with Retry-After; read-budget exhaustion returns 429. query cannot accompany mode. Discovery responses after authentication are private, no-store. Pagination pins source ordering and reapplies current profile eligibility and supported application exclusions. When exact-handle discovery is enabled, a successful empty indexed search may return discovery metadata. This queues bounded FOMO handle acquisition; it never treats a local index failure as a provider miss. Retry the same search after retry_after_seconds for queued/running/retry_scheduled/indexed states. not_found means FomoScan has no matching record, not that the person does not exist. Existing items remain authoritative and unchanged.

## Query parameters

- `query` string
- `limit` integer
- `mode` 'for_you' | 'top_returns' | 'new'
- `period` '7d' | '30d'
- `cursor` string

## Response `200`

Unchanged legacy search items without mode, or a discovery page with items, next_cursor and honest source metadata when mode is supplied.

- union
  - SocialTraderSearchResponse
    - `items` SocialTraderProfile[], required
      - `avatarUrl` string, nullable, required
      - `bio` string, nullable, required
      - `dataVisibility` 'public' | 'private' | 'unknown', required
      - `displayName` string, nullable, required
      - `followers` string, nullable, required
      - `following` string, nullable, required
      - `handle` string, nullable, required
      - `platform` 'fomo' | 'pump', required
      - `platformSubjectId` string, required
      - `portfolioObservedAtMs` string, nullable, required
      - `portfolioValueUsd` string, nullable, required
      - `profileObservedAtMs` string, nullable, required
      - `sevenDayPnlPct` string, nullable, required
      - `sevenDayPnlUsd` string, nullable, required
      - `traderProfileId` string, uuid, required
      - `wallets` object[], required
        - `address` string, required
        - `chainId` string, required
    - `discovery` SocialTraderProfileDiscoveryStatus
      - `state` 'queued' | 'running' | 'indexed' | 'not_found' | 'retry_scheduled' | 'unavailable', required
      - `reason` string, required: Bounded diagnostic category; not a provider error message.
      - `retry_after_seconds` integer, required
  - SocialTraderDiscoveryPage: Fomo-only discovery page. An underfilled or empty page can still have a next_cursor after bounded candidate scanning and exclusions. Follow next_cursor until null; an empty successful page is not an upstream outage. Candidate eligibility is checked against current profiles while the source order stays pinned.
    - `items` SocialTraderDiscoveryItem[], required
      - `avatarUrl` string, nullable, required
      - `bio` string, nullable, required
      - `dataVisibility` 'public' | 'private' | 'unknown', required
      - `displayName` string, nullable, required
      - `followers` string, nullable, required
      - `following` string, nullable, required
      - `handle` string, nullable, required
      - `platform` 'fomo', required
      - `platformSubjectId` string, required
      - `portfolioObservedAtMs` string, nullable, required
      - `portfolioValueUsd` string, nullable, required
      - `profileObservedAtMs` string, nullable, required
      - `sevenDayPnlPct` string, nullable, required: Exact seven-day provider decimal string, including any leading zeroes; null when unavailable.
      - `sevenDayPnlUsd` string, nullable, required: Exact seven-day provider decimal string, including any leading zeroes; null when unavailable.
      - `traderProfileId` string, uuid, required
      - `wallets` object[], required
        - `address` string, required
        - `chainId` string, required
      - `provider_rank` integer, nullable, required: Original Fomo provider rank for Suggested traders and Top traders; null for Recently discovered. Filtering does not renumber ranks.
      - `discovered_at_ms` string, nullable, required: Indexer first-discovery timestamp in milliseconds for Recently discovered; null for the leaderboard modes. This is not account creation time.
    - `next_cursor` string, nullable, required: Opaque seek continuation bound to the authenticated viewer, mode, limit and pinned source snapshot. It grants no access authority.
    - `metadata` union, required
      - object
        - `mode` 'new', required
        - `label` 'Recently discovered', required
        - `source` 'fomo', required
        - `candidate_scope` 'fomo_discovered_profiles', required
        - `actual_period` string, nullable, required
        - `ranking_basis` 'first_discovered', required
        - `personalized` false, required: No learned personalization or ML scoring. Suggested traders applies supported watched/dismissed exclusions to the provider candidate order.
        - `snapshot` string, required: Pinned Indexer discovery head or immutable provider leaderboard snapshot.
        - `observed_at_ms` 'null', nullable, required: Pinned provider observation time in milliseconds. Null for Recently discovered because the discovery head has no observation clock.
      - object
        - `mode` 'for_you', required
        - `label` 'Suggested traders', required
        - `source` 'fomo', required
        - `candidate_scope` 'fomo_provider_top_100', required
        - `actual_period` 'seven_day', nullable, required
        - `ranking_basis` 'provider_leaderboard', required
        - `personalized` false, required: No learned personalization or ML scoring. Suggested traders applies supported watched/dismissed exclusions to the provider candidate order.
        - `snapshot` string, required: Pinned Indexer discovery head or immutable provider leaderboard snapshot.
        - `observed_at_ms` string, nullable, required: Pinned provider observation time in milliseconds. Null for Recently discovered because the discovery head has no observation clock.
      - object
        - `mode` 'top_returns', required
        - `label` 'Top traders', required
        - `source` 'fomo', required
        - `candidate_scope` 'fomo_provider_top_100', required
        - `actual_period` 'seven_day', nullable, required
        - `ranking_basis` 'provider_leaderboard', required
        - `personalized` false, required: No learned personalization or ML scoring. Suggested traders applies supported watched/dismissed exclusions to the provider candidate order.
        - `snapshot` string, required: Pinned Indexer discovery head or immutable provider leaderboard snapshot.
        - `observed_at_ms` string, nullable, required: Pinned provider observation time in milliseconds. Null for Recently discovered because the discovery head has no observation clock.

## Other responses

- `400`: Stable machine-readable problem. HTTP 429 and 503 responses include retry and cache-validity fields plus Retry-After and X-Request-ID headers.
- `401`: Stable machine-readable problem. HTTP 429 and 503 responses include retry and cache-validity fields plus Retry-After and X-Request-ID headers.
- `429`: Stable machine-readable problem. HTTP 429 and 503 responses include retry and cache-validity fields plus Retry-After and X-Request-ID headers.
- `501`: Discovery capability or period is unsupported. HTTP 501 does not include Retry-After or retryable fields; waiting does not enable the capability.
- `503`: Stable machine-readable problem. HTTP 429 and 503 responses include retry and cache-validity fields plus Retry-After and X-Request-ID headers.

---

[API](https://skmtc.dev/arbital/apis/arbital-api.md) - [All operations](https://skmtc.dev/arbital/apis/arbital-api/llms.txt) - [OpenAPI document](https://skmtc.dev/arbital/apis/arbital-api/revisions/bb0185edf43a?raw)