> ## 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.

# API reference

> Real-time payment infrastructure for autonomous agents and services.

<Note>
  To activate your agent account after registration, contact [hello@pulsarpay.io](mailto:hello@pulsarpay.io).
</Note>

## Base URL

All API requests are made to:

```
https://www.pulsarpay.io
```

## Authentication

PulsarPay uses a dual-key model. The key required depends on the endpoint.

<CardGroup cols={2}>
  <Card title="x-agent-key" icon="robot">
    Identifies the agent or service performing the request. Obtained at registration.
  </Card>

  <Card title="x-user-key" icon="user">
    Represents the user who has authorized the agent to charge their balance.
  </Card>
</CardGroup>

Endpoints that perform charges require **both** headers. Read-only endpoints (earnings, charge listing) only require `x-agent-key`.

## Charge authorization

A charge is processed only when all four conditions are met:

1. `x-agent-key` is valid
2. `x-user-key` is valid
3. The user has sufficient balance
4. The agent is authorized to charge on behalf of the user

The user key acts as delegated authorization — the user explicitly provides it to grant the agent permission to charge per request. This enables secure, per-request billing with a clear separation between who executes and who pays.

## Ecosystem

<CardGroup cols={2}>
  <Card title="Users" icon="user">
    Fund their balance, generate API keys, and authorize agents to charge their account per request.
  </Card>

  <Card title="Agents" icon="robot">
    Integrate with PulsarPay to charge users in real time. Earnings accumulate in their balance and can be withdrawn on demand.
  </Card>
</CardGroup>

## Endpoints

<CardGroup cols={2}>
  <Card title="Register agent" icon="id-card" href="/docs/api-reference/endpoint/register-agent">
    Create a new agent and receive your API key.
  </Card>

  <Card title="Create charge" icon="bolt" href="/docs/api-reference/endpoint/create-charges">
    Debit a user's balance for a service request.
  </Card>

  <Card title="Get charge" icon="magnifying-glass" href="/docs/api-reference/endpoint/get-charge-by-id">
    Retrieve status and details for a specific charge.
  </Card>

  <Card title="List charges" icon="list" href="/docs/api-reference/endpoint/get-charges">
    Paginated charge history for auditing and reconciliation.
  </Card>

  <Card title="Earnings" icon="chart-line" href="/docs/api-reference/endpoint/earnings">
    View net earnings and total successful charges.
  </Card>

  <Card title="Withdraw" icon="wallet" href="/docs/api-reference/endpoint/withdraw">
    Transfer earnings to your wallet.
  </Card>
</CardGroup>