> ## Documentation Index
> Fetch the complete documentation index at: https://www.pulsarpay.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Integrate Pulsarpay into your API or autonomous agent in minutes.

## Prerequisites

* Node.js 18 or higher
* A Pulsarpay agent key (`ag_live_...`)

<Note>
  Don't have an agent key yet? [Register your agent](#register-an-agent) first — the key is returned only once at registration.
</Note>

## Install the SDK

<CodeGroup>
  ```bash npm theme={null}
  npm install pulsarpay-sdk
  ```

  ```bash pnpm theme={null}
  pnpm add pulsarpay-sdk
  ```

  ```bash yarn theme={null}
  yarn add pulsarpay-sdk
  ```
</CodeGroup>

## Initialize the client

```typescript theme={null}
import { PulsarpayClient } from "Pulsarpay-sdk";

const client = new PulsarpayClient({
  agentKey: process.env.PULSARPAY_AGENT_KEY!,  //no required for register agent
});
```

Optional configuration:

```typescript theme={null}
const client = new PulsarpayClient({
  agentKey: "ag_live_...",  // required
  baseUrl: "https://...",   // defaults to https://www.pulsarpay.io
  timeout: 15_000,          // defaults to 30000ms
});
```

## Register an agent

Run this once during onboarding. **Save the returned `apiKey` immediately** — it is not retrievable afterward.

```typescript theme={null}
const result = await client.agents.register({
  name: "my-inference-agent",
  email: "dev@mycompany.com",
  website: "https://mycompany.com",
});

console.log(result.apiKey);   // ag_live_... (save this!)
console.log(result.enabled);  // false — contact hello@pulsarpay.io for activation
```

## Core operations

<Steps>
  <Step title="Create a charge">
    Debit a user's balance. An idempotency key is auto-generated if you don't provide one.

    Each currency has a separate balance. The charge is deducted from the user's balance in the specified currency — the user must have sufficient funds in that currency.

    ```typescript theme={null}
    const charge = await client.payments.createCharge(
      {
        amount: 0.5,
        currency: "USD",  // "USD" or "USDC"
        description: "AI Inference - 1000 tokens",
      },
      {
        userKey: "pp_live_7698774c...",
        // idempotencyKey: "uuid-v4-optional",
      }
    );

    console.log(charge.chargeId); // cmnnfoagf0003jk04suqxf3k9
    console.log(charge.reused);   // true if idempotency key was reused
    ```
  </Step>

  <Step title="Check charge status">
    Poll a charge by ID. Status is one of `PENDING`, `SUCCESS`, `FAILED`, or `EXPIRED`.

    ```typescript theme={null}
    const charge = await client.payments.getCharge("cmn3tney00001l104hudm7fgy");

    console.log(charge.status);   // "PENDING" | "SUCCESS" | "FAILED"
    console.log(charge.amount);   // 0.5
    console.log(charge.currency); // "USD" | "USDC"
    ```
  </Step>

  <Step title="List charges">
    Retrieve paginated charge records for auditing and reconciliation.

    ```typescript theme={null}
    const result = await client.payments.listCharges({ page: 1, limit: 20 });

    console.log(result.pagination.total);      // 142
    console.log(result.pagination.totalPages); // 8

    for (const charge of result.data) {
      console.log(charge.id, charge.status, charge.amount);
    }
    ```
  </Step>

  <Step title="View earnings">
    Each currency has its own independent balance. The response returns one entry per currency.

    ```typescript theme={null}
    const { earnings } = await client.payments.getEarnings();

    for (const entry of earnings) {
      console.log(entry.currency);       // "USD" | "USDC"
      console.log(entry.totalEarned);    // 8.5
      console.log(entry.totalCharges);   // 3
      console.log(entry.currentBalance); // 8.5
    }
    ```
  </Step>

  <Step title="Withdraw funds">
    Withdraw to a Solana wallet (USDC) or a PayPal account (USD). Minimum withdrawal is 1.00. A 3% platform fee is deducted from the gross amount.

    ```typescript theme={null}
    // USD → PayPal
    const payout = await client.payments.withdraw({
      amount: 10.00,
      currency: "USD",
      walletAddress: "your-paypal-id@example.com",
    });

    // USDC → Solana wallet
    const payout = await client.payments.withdraw({
      amount: 10.00,
      currency: "USDC",
      walletAddress: "8ixbQzsFc9FkxegG7aumq3h1XCGDkRSN23xeLTnZiyHr",
    });

    console.log(payout.success);                  // true
    console.log(payout.payoutId);                 // cmnpeptvy0005l404gq5zy7nx
    console.log(payout.breakdown.netAmount);      // 9.70
    console.log(payout.breakdown.network);        // "PAYPAL" | "SOL"
    ```
  </Step>
</Steps>

## Error handling

The SDK provides specific error classes for each failure scenario.

```typescript theme={null}
import {
  PulsarpayInsufficientFundsError,
  PulsarpayUnauthorizedError,
  PulsarpayBadRequestError,
  PulsarpayNotFoundError,
  PulsarpayConflictError,
  PulsarpayNetworkError,
  PulsarpayError,
} from "Pulsarpay-sdk";

try {
  await client.payments.createCharge(data, options);
} catch (err) {
  if (err instanceof PulsarpayInsufficientFundsError) {
    console.error("User has no funds:", err.message);
  } else if (err instanceof PulsarpayUnauthorizedError) {
    console.error("Invalid agent or user key:", err.message);
  } else if (err instanceof PulsarpayBadRequestError) {
    console.error("Validation error:", err.message);
  } else if (err instanceof PulsarpayNetworkError) {
    console.error("Network/timeout error:", err.message);
  } else if (err instanceof PulsarpayError) {
    console.error(`Unexpected error [${err.statusCode}]:`, err.message);
  }
}
```

| Error class                       | Status            |
| --------------------------------- | ----------------- |
| `PulsarpayBadRequestError`        | 400               |
| `PulsarpayUnauthorizedError`      | 401               |
| `PulsarpayInsufficientFundsError` | 402               |
| `PulsarpayNotFoundError`          | 404               |
| `PulsarpayConflictError`          | 409               |
| `PulsarpayNetworkError`           | Network / timeout |

## Next steps

<CardGroup cols={2}>
  <Card title="API reference" icon="code" href="/docs/api-reference/introduction">
    Full endpoint documentation with request and response schemas.
  </Card>

  <Card title="Create charges" icon="bolt" href="/docs/api-reference/endpoint/create-charges">
    Detailed options for charge creation and idempotency.
  </Card>

  <Card title="Earnings" icon="chart-line" href="/docs/api-reference/endpoint/earnings">
    Track net earnings and transaction history.
  </Card>

  <Card title="Withdraw" icon="wallet" href="/docs/api-reference/endpoint/withdraw">
    Transfer USDC to a Solana wallet or USD to a PayPal account.
  </Card>
</CardGroup>