---
name: aura-browser-sdk
description: Use when an agent is building or debugging browser-side Aura integrations that need Sign in with Aura, read-only user/profile/inventory/pack/catalog/offer data, or a decision between hosted Aura SDK helpers and raw public API routes. Prefer the SDK for browser apps; use raw API only for server-side integrations, non-browser agents, bridges, or SDK gaps.
---

# Aura Browser SDK

Use this skill for browser-side Aura identity and read-only data. It is intentionally read-only: it does not export bearer tokens, signing keys, passkey secrets, or write permissions.

## First Decision

- Browser app needs current user, wallet, profile, inventory, pack, catalog, or offer data: use the hosted Aura SDK.
- Server-side integration, backend job, bridge, non-browser agent, or SDK gap: use the OpenAPI or compact public schema instead.
- Create, buy, sell, offer, transfer, mint, or open actions for a real user: leave this skill and use delegated-user developer auth.
- Backend-owned service-wallet checkout/open/mint-open: leave this skill and use the service-wallet marketplace skill.

Do not invent app-local profile or inventory proxy routes for browser reads unless the app needs its own aggregation layer. In a browser app, start with `Aura.getUser`, `Aura.getCurrentInventory`, and `Aura.getInventory`.

## Intent Map

- current signed-in profile: `Aura.getUser({ refresh: true })`
  - Use when: The app already loaded Login with Aura and needs the fresh public profile for the connected user.
  - Recipe: Aura Caps profile and verification
  - Avoid: Do not call /api/users/lookup?username=<wallet> from browser code.
- profile by wallet address: `Aura.getUser({ walletAddress: '0x...' })`
  - Use when: A partner has only a wallet address and needs username, avatar, X, Discord, followers, or following.
  - Recipe: Aura Caps profile and verification
  - Avoid: Do not pass a valid 0x address as username to a custom proxy route.
- current signed-in inventory: `Aura.getCurrentInventory({ collection?, limit? })`
  - Use when: A browser app needs the logged-in user's owned inventory after Sign in with Aura.
  - Recipe: Current user and inventory
  - Avoid: Do not hand-build profile lookup plus pack-cards calls.
- inventory by wallet: `Aura.getInventory({ userAddress: '0x...', collection?, limit? })`
  - Use when: A partner needs inventory for a wallet-shaped profile ref, optionally scoped to one collection.
  - Recipe: Inventory by wallet with collection art
  - Avoid: Do not invent /api/aura-profile or /api/aura-inventory app routes unless the app adds its own aggregation.
- collection traits and card details: `Aura.getInventory({ userAddress, collection, condensed: true })`
  - Use when: A game or profile UI needs item traits, details text, collection identity, and pack/back art from inventory rows.
  - Recipe: Traits, details, and collection styling
  - Avoid: Do not parse the human details string for traits; use attributes, traits, and traitList.
- pack or collection metadata: `Aura.getPack(slugOrAddress)`
  - Use when: A browser app needs collection-level metadata before reading inventory or market data.
  - Recipe: Pack and market reads
  - Avoid: Do not hardcode pack ids when a slug or contract address can be resolved by the SDK.
- market catalog and offers: `Aura.getMarketplaceCatalog(options) and Aura.getMarketplaceOffers(options)`
  - Use when: A read-only browser UI needs catalog or offer state without write auth.
  - Recipe: Pack and market reads
  - Avoid: Do not use delegated-user or service-wallet auth for read-only market surfaces.

## Install

```html
<script src="https://auramaxx.gg/login-with-aura/sdk.js" data-aura-origin="https://auramaxx.gg"></script>
<script>
  Aura.configure({
    clientId: "your-app",
    readToken: "aura_pk_..."
  });
</script>
```

## Preferred Helpers

- `Aura.getUser`: Looks up the current user, a username, a wallet address, or a user id. Pass refresh: true to fetch the full public profile for the signed-in user. Use for current signed-in profile, profile by wallet, profile by username, profile by user id. Aliases: `Aura.getProfile`, `Aura.api.getUser`.
- `Aura.getInventory`: Reads a user's owned inventory. collection accepts a slug or contract address and collections accepts multiple. Use for profile inventory, inventory by wallet, inventory by collection. Aliases: `Aura.api.getInventory`.
- `Aura.getCurrentUserInventory`: Reads inventory for the current page-session user without passing a separate user ref. Use for current signed-in inventory, current inventory by collection. Aliases: `Aura.getCurrentInventory`, `Aura.api.getCurrentInventory`, `Aura.api.getCurrentUserInventory`.
- `Aura.getCurrentInventory`: Friendly alias for Aura.getCurrentUserInventory. Use for current signed-in inventory, current inventory by collection. Aliases: `Aura.getCurrentUserInventory`.
- `Aura.getCreatedPacks`: Reads packs created by a user. Use for created packs, creator collections. Aliases: `Aura.api.getCreatedPacks`.
- `Aura.getPack`: Reads a pack by slug or contract address. Use for pack detail, collection detail. Aliases: `Aura.getPackDetail`, `Aura.api.getPack`.
- `Aura.getPackStatic`: Reads static pack metadata. Use for static pack metadata. Aliases: `Aura.api.getPackStatic`.
- `Aura.getPackLive`: Reads live pack market and status data. Use for live pack status, live pack market state. Aliases: `Aura.api.getPackLive`.
- `Aura.getMarketplaceCatalog`: Reads the public marketplace catalog. Use for marketplace catalog, public catalog. Aliases: `Aura.getCatalog`, `Aura.api.getMarketplaceCatalog`.
- `Aura.getMarketplaceOffers`: Reads public marketplace offers. Passing a string delegates to Aura.getMarketplaceSkuOffers. Use for marketplace offers, offers by wallet. Aliases: `Aura.getOffers`, `Aura.api.getMarketplaceOffers`.
- `Aura.getMarketplaceSkuOffers`: Reads public offers for one marketplace agent or SKU. Use for offers by agent id, offers by sku. Aliases: `Aura.api.getMarketplaceSkuOffers`.
- `Aura.getMarketplaceV2Offers`: Reads the v2 public marketplace offers surface. Use for v2 marketplace offers, order-book offers. Aliases: `Aura.api.getMarketplaceV2Offers`.

## Recipes

### Current user and inventory
Use this in browser apps after loading the hosted SDK. It avoids raw user lookup and pack-cards calls.

```js
Aura.configure({ clientId: "your-app", readToken: "aura_pk_..." });

const session = Aura.getSession() || await Aura.signIn({ clientId: "your-app" });
const user = await Aura.getUser({ refresh: true });
const inventory = await Aura.getCurrentInventory({ limit: 200 });
const items = inventory.items || inventory.data;

console.log(session.walletAddress, user.username, items);
```

### Inventory by collection
Use collection slugs or contract addresses; the SDK resolves pack ids and keeps pagination normalized.

```js
const inventory = await Aura.getInventory({
  userAddress: "0xUSER...",
  collection: "aura-caps-test",
  limit: 200
});

const caps = inventory.items.filter((item) => item.type === "LOOT");
console.log(caps[0]?.collectionName, caps[0]?.attributes, caps[0]?.traitList);
```

### Pack and market reads
Use SDK read helpers for pack detail, catalog, and offer state in browser apps.

```js
const pack = await Aura.getPack("aura-caps-test");
const catalog = await Aura.getMarketplaceCatalog({ project: "auramaxxgg" });
const offers = await Aura.getMarketplaceOffers({ address: Aura.getWalletAddress() });

console.log(pack.pack?.name, catalog, offers);
```

### Aura Caps profile and verification
Use this when a partner has a wallet or current session and wants profile, X, and Discord state without a custom /api/aura-profile route.

```js
Aura.configure({ clientId: "aura-caps", readToken: "aura_pk_..." });

const session = Aura.getSession() || await Aura.signIn({ clientId: "aura-caps" });
const profile = await Aura.getUser({ refresh: true });
const byWallet = await Aura.getUser({ walletAddress: session.walletAddress });

console.log({
  username: profile.username || byWallet.username,
  wallet: session.walletAddress,
  x: profile.xConnected ? profile.xHandle : null,
  discord: profile.discordConnected
    ? profile.discordGlobalName || profile.discordUsername
    : null
});
```

### Inventory by wallet with collection art
Use this when a game needs owned items for one wallet and one collection, plus the collection/back image fields.

```js
const inventory = await Aura.getInventory({
  userAddress: "0xUSER...",
  collection: "aura-caps-test",
  limit: 200
});

const items = inventory.items || inventory.data;
const first = items[0];

console.log({
  collectionName: first?.collectionName,
  collectionSlug: first?.collectionSlug,
  collectionImage: first?.collectionImage,
  packImage: first?.packImage,
  itemImage: first?.image
});
```

### Traits, details, and collection styling
Use fields directly from condensed inventory rows; details is display copy, while traits and attributes are structured data.

```js
const inventory = await Aura.getCurrentInventory({
  collection: "aura-caps-test",
  condensed: true,
  limit: 200
});

const cap = inventory.items.find((item) => item.type === "LOOT");
const traits = cap?.traitList || Object.entries(cap?.traits || {}).map(([trait_type, value]) => ({
  trait_type,
  value
}));

console.log({
  details: cap?.details,
  traits,
  rawAttributes: cap?.attributes,
  backArt: cap?.packImage || cap?.collectionImage
});
```

## Inventory Response Shape

`Aura.getInventory`, `Aura.getCurrentInventory`, and `Aura.getCurrentUserInventory` return normalized pagination aliases: `items` and `data`, plus `meta` and `pagination`. Prefer `items` in app code.

- `attributes`: Record<string, unknown>
- `collectionAddress`: string | null
- `collectionId`: string | null
- `collectionImage`: string | null
- `collectionName`: string | null
- `collectionSlug`: string | null
- `details`: string | null
- `image`: string | null
- `name`: string
- `packImage`: string | null
- `packName`: string
- `traitList`: { trait_type, value }[]
- `traits`: Record<string, unknown>
- `type`: AURA | PACK | LOOT
- `weight`: number | null

## Machine-Readable Sources

- SDK manifest: https://auramaxx.gg/login-with-aura/sdk.manifest.json
- SDK API JSON: https://auramaxx.gg/docs/sdk-api.json
- SDK TypeScript declarations: https://auramaxx.gg/login-with-aura/sdk.d.ts
- SDK diagnostics page: https://auramaxx.gg/login-with-aura/diagnostics
- Human SDK API docs: https://auramaxx.gg/docs/sdk-api
- LLM index: https://auramaxx.gg/llms.txt
- Raw API fallback schema: https://auramaxx.gg/auramaxxgg-public-api-schema-v1.json
- OpenAPI fallback: https://auramaxx.gg/auramaxxgg-tempo-openapi-v1.json

## Troubleshooting

- If a profile lookup gets a wallet-shaped username, pass it to `Aura.getUser` or pass `{ userAddress: "0x..." }` to inventory helpers; the SDK handles wallet, username, and user-id refs.
- If current profile data looks stale, call `Aura.getUser({ refresh: true })` after `Aura.getSession()` or `Aura.signIn()`.
- If inventory cards need collection styling, use `collectionName`, `collectionSlug`, `collectionAddress`, `collectionImage`, and `packImage` from each item.
- If traits look missing, inspect both `traits` and `attributes`; `traitList` is the OpenSea-style array form.
- If the SDK cannot run in the target environment, document the reason and then use raw public GET routes from the API schema.