# Light — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search Destiny 2 weapons by name or perks and instantly access detailed stats, popular god rolls, and perk combination ratings to optimize your loadouts. Compare weapon data and discover top-performing gear configurations to dominate in PvP and PvE activities.

**Category:** Entertainment | **Website:** [light.gg/](https://light.gg/) | **Docs:** [parse.bot/marketplace/22835138-718b-4848-8baf-4c93c42f6c18/light-gg-api](https://parse.bot/marketplace/22835138-718b-4848-8baf-4c93c42f6c18/light-gg-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/light/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Get popular weapons

Retrieve the current top 25 popular weapons from light.gg's god roll popularity rankings. Rankings reflect community usage data and update regularly. Each weapon includes its rank position, Bungie hash ID, name, and light.gg URL.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/light/get-popular-weapons \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get weapon details

Fetch full details for a weapon by its Bungie item hash ID. Combines Bungie API manifest data (name, type, stats) with light.gg community data (perk popularity percentages, popular trait combinations, community insight text, and user reviews with PvE/PvP ratings). Exotic weapons have fixed perks so perks_popularity may be empty. Each review includes nested comment data with votes and child replies.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `item_id` | string | Yes | Bungie item hash ID (numeric string, e.g. '347366834' for Ace of Spades). Obtainable from search_weapons or get_popular_weapons results. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/light/get-weapon-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"item_id":"<string>"}'
```

### Search by perks

Search for weapons that have specific perk combinations using perk IDs.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `perk_ids` | string | Yes | Comma-separated perk hashes/IDs (e.g., 2344383760,12345678) |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/light/search-by-perks \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"perk_ids":"<string>"}'
```

### Search weapons

Full-text search over light.gg's weapon and item database by name. Returns matching items with their Bungie hash IDs and light.gg URLs. Results include weapons, catalysts, ornaments, and other named items whose title matches the query.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search term for weapon or item name (e.g. 'ace of spades', 'hand cannon') |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/light/search-weapons \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.