builder-data

通过 Talent Protocol API 查询构建者声誉数据。获取构建者排名、验证人员、解析身份 (Twitter/Farcaster/GitHub/wallet)、按位置/国家/地区搜索、获取凭证并利用 GitHub 数据进行丰富。

# Talent Powers

Query professional data from [Talent Protocol](https://talent.app) - a platform that tracks builders

**Use this skill to:**
- Find verified developers by location, skills, or identity (Twitter/GitHub/Farcaster/wallet)
- Check builder reputation (ranks by default, scores only when asked)
- Map Twitter accounts with Wallet addresses
- Verify human identity from a wallet
- Search for builder's credentials (earnings, contributions, hackathons, contracts, etc)
- Check the projects each builder is shipping

## Required Credentials

| Variable | Required | Description | Get it at |
|----------|----------|-------------|-----------|
| `TALENT_API_KEY` | **Yes** | API key for Talent Protocol (read access to profile/identity data) | https://talent.app/~/settings/api |
| `GITHUB_TOKEN` | No | Personal access token for higher GitHub rate limits (60/hr → 5,000/hr) | https://github.com/settings/tokens |

**Base URL:** `https://api.talentprotocol.com`

```bash
curl -H "X-API-KEY: $TALENT_API_KEY" "https://api.talentprotocol.com/..."
```

## Endpoints

| Endpoint | Purpose |
|----------|---------|
| `/search/advanced/profiles` | Search profiles by identity, tags, rank, verification |
| `/profile` | Get profile by ID |
| `/accounts` | Get connected wallets, GitHub, socials |
| `/socials` | Get social profiles + bios |
| `/credentials` | Get data points (earnings, followers, hackathons, etc.) |
| `/human_checkmark` | Check if human-verified (optional, don't use by default) |
| `/scores` | Get ranks (default) or scores (only when explicitly asked) |

## Key Parameters

**Identity lookup:**
```
query[identity]={handle}&query[identity_type]={twitter|github|farcaster|ens|wallet}
```

**Filters (all optional, only use when relevant to the query):**
```
query[tags][]=developer              # filter by tag (developer, designer, etc.)
query[verified_nationality]=true     # only verified nationality
query[human_checkmark]=true          # only human-verified (reduces results significantly)
```

**Sorting:**
```
sort[score][order]=desc&sort[score][scorer]=Builder%20Score
```

**Pagination:** `page=1&per_page=250` (max 250)

## URL Encoding

`[` = `%5B`, `]` = `%5D`, Space = `%20`

## Response Fields

**Default → Ranks (always use unless user asks for scores):**
- `builder_score.rank_position` - Primary rank metric
- `scores[].rank_position` where `slug = "builder_score"` - Latest rank

**Only when user explicitly asks for scores:**
- `builder_score.points` - Score value
- `scores[].points` - Individual score values

- `location` - User-entered location (returned in response)

## Location Filter

**DO NOT USE** `query[standardized_location]=Country` - doesn't work.

**USE `customQuery` with regex:**

```bash
curl -X POST -H "X-API-KEY: $TALENT_API_KEY" -H "Content-Type: application/json" \
  "https://api.talentprotocol.com/search/advanced/profiles" \
  -d '{
    "customQuery": {
      "regexp": {
        "standardized_location": {
          "value": ".*argentina.*",
          "case_insensitive": true
        }
      }
    },
    "sort": { "score": { "order": "desc", "scorer": "Builder Score" } },
    "perPage": 50
  }'
```

See [use-cases.md](references/use-cases.md#by-location-country) for more examples.

## Limitations

- Max 250 per page
- GET only for most endpoints (POST for customQuery)
- Simple `query[standardized_location]` param broken - use `customQuery` regex

## GitHub Enrichment

Get projects/repos via GitHub after resolving username from `/accounts`:

```bash
# 1. Get GitHub username
/accounts?id={profile_id} → { "source": "github", "username": "..." }

# 2. Query GitHub
GET https://api.github.com/users/{username}                           # Profile
GET https://api.github.com/users/{username}/repos?sort=stars&per_page=5   # Top repos
GET https://api.github.com/users/{username}/repos?sort=pushed&per_page=5  # Recent
GET https://api.github.com/users/{username}/events/public             # Commits
GET https://api.github.com/search/issues?q=author:{username}+type:pr+state:open  # Open PRs
```

**GitHub Token (recommended):** Without a token, GitHub limits to 60 requests/hr. With a personal access token, you get 5,000/hr.
- Create one at: https://github.com/settings/tokens → "Generate new token (classic)" → no scopes needed for public data
- Use it: `-H "Authorization: token $GITHUB_TOKEN"`

## References

- [endpoints.md](references/endpoints.md) - Full endpoint docs
- [use-cases.md](references/use-cases.md) - Common patterns
- [github-enrichment.md](references/github-enrichment.md) - GitHub data

---

## 中文说明

# Talent Powers

查询来自 [Talent Protocol](https://talent.app) 的专业数据 —— 一个追踪构建者的平台

**使用此技能可以：**
- 按位置、技能或身份 (Twitter/GitHub/Farcaster/wallet) 查找经过验证的开发者
- 检查构建者声誉（默认按排名，仅在被要求时显示分数）
- 将 Twitter 账号与钱包地址映射关联
- 从钱包验证真人身份
- 搜索构建者的凭证（收入、贡献、黑客松、合约等）
- 查看每位构建者正在交付的项目

## 所需凭证

| 变量 | 是否必需 | 描述 | 获取地址 |
|----------|----------|-------------|-----------|
| `TALENT_API_KEY` | **是** | Talent Protocol 的 API 密钥（对个人资料/身份数据的读取权限） | https://talent.app/~/settings/api |
| `GITHUB_TOKEN` | 否 | 用于提高 GitHub 速率限制的个人访问令牌 (60/hr → 5,000/hr) | https://github.com/settings/tokens |

**Base URL:** `https://api.talentprotocol.com`

```bash
curl -H "X-API-KEY: $TALENT_API_KEY" "https://api.talentprotocol.com/..."
```

## 端点

| 端点 | 用途 |
|----------|---------|
| `/search/advanced/profiles` | 按身份、标签、排名、验证状态搜索个人资料 |
| `/profile` | 按 ID 获取个人资料 |
| `/accounts` | 获取关联的钱包、GitHub、社交账号 |
| `/socials` | 获取社交资料 + 简介 |
| `/credentials` | 获取数据点（收入、粉丝、黑客松等） |
| `/human_checkmark` | 检查是否经过真人验证（可选，默认不使用） |
| `/scores` | 获取排名（默认）或分数（仅在明确要求时） |

## 关键参数

**身份查找：**
```
query[identity]={handle}&query[identity_type]={twitter|github|farcaster|ens|wallet}
```

**过滤器（均为可选，仅在与查询相关时使用）：**
```
query[tags][]=developer              # filter by tag (developer, designer, etc.)
query[verified_nationality]=true     # only verified nationality
query[human_checkmark]=true          # only human-verified (reduces results significantly)
```

**排序：**
```
sort[score][order]=desc&sort[score][scorer]=Builder%20Score
```

**分页：** `page=1&per_page=250`（最大 250）

## URL 编码

`[` = `%5B`，`]` = `%5D`，空格 = `%20`

## 响应字段

**默认 → 排名（除非用户要求分数，否则始终使用）：**
- `builder_score.rank_position` - 主要排名指标
- `scores[].rank_position` 其中 `slug = "builder_score"` - 最新排名

**仅在用户明确要求分数时：**
- `builder_score.points` - 分数值
- `scores[].points` - 各项分数值

- `location` - 用户输入的位置（在响应中返回）

## 位置过滤器

**请勿使用** `query[standardized_location]=Country` —— 无效。

**改用带正则表达式的 `customQuery`：**

```bash
curl -X POST -H "X-API-KEY: $TALENT_API_KEY" -H "Content-Type: application/json" \
  "https://api.talentprotocol.com/search/advanced/profiles" \
  -d '{
    "customQuery": {
      "regexp": {
        "standardized_location": {
          "value": ".*argentina.*",
          "case_insensitive": true
        }
      }
    },
    "sort": { "score": { "order": "desc", "scorer": "Builder Score" } },
    "perPage": 50
  }'
```

更多示例请参阅 [use-cases.md](references/use-cases.md#by-location-country)。

## 局限性

- 每页最多 250 条
- 大多数端点仅支持 GET（customQuery 使用 POST）
- 简单的 `query[standardized_location]` 参数已失效 —— 使用 `customQuery` 正则表达式

## GitHub 数据丰富

在从 `/accounts` 解析出用户名后，通过 GitHub 获取项目/仓库：

```bash
# 1. Get GitHub username
/accounts?id={profile_id} → { "source": "github", "username": "..." }

# 2. Query GitHub
GET https://api.github.com/users/{username}                           # Profile
GET https://api.github.com/users/{username}/repos?sort=stars&per_page=5   # Top repos
GET https://api.github.com/users/{username}/repos?sort=pushed&per_page=5  # Recent
GET https://api.github.com/users/{username}/events/public             # Commits
GET https://api.github.com/search/issues?q=author:{username}+type:pr+state:open  # Open PRs
```

**GitHub 令牌（推荐）：** 没有令牌时，GitHub 限制为每小时 60 次请求。使用个人访问令牌后，可达每小时 5,000 次。
- 创建地址：https://github.com/settings/tokens → "Generate new token (classic)" → 公开数据无需任何 scope
- 使用方式：`-H "Authorization: token $GITHUB_TOKEN"`

## 参考资料

- [endpoints.md](references/endpoints.md) -