Skip to main content

Getting Started

This guide gets you up and running quickly.

Installation​

npm install poe-js-sdk

Official API – Profile​

import { PoEApiClient, OAuthHelper } from 'poe-js-sdk';

const oauthConfig = {
  clientId: 'your-client-id',
  redirectUri: 'http://localhost:8080/callback',
  scopes: ['account:profile', 'account:characters'],
};

const pkce = await OAuthHelper.generatePKCE();
const authUrl = OAuthHelper.buildAuthUrl(oauthConfig, 'random-state', pkce);
console.log('Visit:', authUrl);

// After callback
const tokens = await OAuthHelper.exchangeCodeForToken(
  { ...oauthConfig, userAgent: 'OAuth myapp/1.0.0 (contact: you@example.com)' },
  'code',
  pkce.codeVerifier
);

const client = new PoEApiClient({
  accessToken: tokens.access_token,
  userAgent: 'OAuth myapp/1.0.0 (contact: you@example.com)',
});

const profile = await client.getProfile();
console.log(`Hello, ${profile.name}!`);

SPA Auth Helper (PKCE)​

import { createBrowserAuth } from 'poe-js-sdk/browser-auth';
import { PoEApiClient } from 'poe-js-sdk';

const auth = createBrowserAuth({
  clientId: 'your-client-id',
  redirectUri: 'http://localhost:8080/callback',
  scopes: ['account:profile'],
});

auth.login();
await auth.handleRedirectCallback();

const client = new PoEApiClient({
  userAgent: 'OAuth myapp/1.0.0 (contact: you@example.com)',
  accessToken: await auth.getAccessToken(),
});

// Note on scopes:
// - Use account:* scopes for user login.
// - Use service:* scopes separately via the Client Credentials grant (confidential clients only) on your server.

Trade Search – Quick Example (Unofficial)​

import { TradeClient, TradeQueryBuilder, ItemCategories, Currencies } from 'poe-js-sdk';

const tradeClient = new TradeClient({
  poesessid: 'your-poesessid-cookie',
});

const query = new TradeQueryBuilder()
  .onlineOnly(true)
  .category(ItemCategories.ACCESSORY_RING)
  .price(Currencies.CHAOS, 1, 50)
  .andStats([{ id: 'explicit.stat_3299347043', min: 70 }])
  .build();

const results = await tradeClient.searchAndFetch('Standard', query, 10);
console.log(`Found ${results.search.total} rings`);

Next Steps​

  • Read the detailed guides (OAuth, Trade, Rate Limiting)
  • Learn more about SPA auth: Browser Auth (SPA)
  • Explore the API Reference
  • Try the examples/ directory in the repository