> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pulseshiga.io/llms.txt
> Use this file to discover all available pages before exploring further.
# @pulsebyshiga/node
> Server-side SDK reference — client construction, collection sessions and orders, rate preview, webhook verification, error classes, and the shared wire types.
The server-side SDK. It holds your secret key, mints single-order sessions,
looks up order ground truth, previews rates, and verifies signed webhooks.
Methods return the value directly and throw typed errors — see
[Error handling](/backend/errors) for the catch pattern.
This surface reflects the `@pulsebyshiga/node` types — the working view of the API
until the canonical Pulse OpenAPI contract is published. Wire shapes
(snake\_case JSON, decimal-string amounts) are stable; a few fields are still
being reconciled and are flagged where they appear.
## Client construction
Construct the client once with an auth descriptor and optional settings.
```ts theme={null}
import Pulse, { useApiKey } from '@pulsebyshiga/node';
const pulse = new Pulse(useApiKey(process.env.PULSE_API_KEY!), {
webhookSecret: process.env.PULSE_WEBHOOK_SECRET,
});
```
The constructor is `new Pulse(auth, options)`. `auth` is either a bare API-key
string (treated as `useApiKey`) or an auth descriptor from one of the two
helpers below.
### Auth helpers
Full engine access with the partner's root secret. **Server-side only** — the
client throws `PulseAccessError` if an API key is constructed where `window`
is defined.
Scope every call to one order's short-lived session token (`cs_*`).
Browser-safe. The session token is a scoped-down delegate the API key mints,
so a caller holds one or the other, never both.
### Options
Default secret for `webhooks.verify()` / `verifyOnce()`. Can also be passed
per call.
Backing store for `verifyOnce()` de-duplication. Defaults to an in-memory
store (single process). Supply a shared store (Redis, a database table)
implementing `has(eventId)` / `add(eventId)` for multi-instance deployments.
Override the API host (e.g. a local or sandbox test server). Otherwise the live
engine host is used.
Retries on network errors, 429, and 5xx.
Base backoff delay, doubled per attempt.
Custom `fetch` implementation.
## collectionSessions.create
```ts theme={null}
const session = await pulse.collectionSessions.create(params, { idempotencyKey });
```
Creates a collection order plus the single-order session token the hosted flow
is opened with. See [Create a session](/backend/create-session) for the naira
and USD gate walkthrough.
### Parameters
The payload is a discriminated union on `gate`. Provide **exactly one** of
`target` (fiat side) or `source` (crypto side).
Which fiat gate the session settles through.
Value direction. `offramp` = crypto in → fiat out; `onramp` = fiat in → crypto
out.
Fiat side — provide this OR `source`.
Decimal string, e.g. `"1000000.00"`.
Crypto side (offramp) — the amount of `asset` to send; the fiat target is
derived from it.
Lowercase network name (see [Types](#types)).
Your own reference for this order.
Naira gate only. Your stable reference for the end user.
Naira gate only. Either provisions a named virtual account on first use, or
references an existing one.
`true` to provision a new account, `false` to reference an existing one.
When `provision: true`. Sensitive — server-to-server only; never reaches
the hosted flow.
When `provision: true`. Sensitive — server-to-server only; never reaches
the hosted flow.
When `provision: false`.
The USD gate carries no `user_ref` and no `account` block — funds land in your
omnibus rather than a per-user account.
### Options
Client idempotency key; auto-generated when omitted. Key it off your own
deposit/order id so a retried request mints the same session.
### Response — CollectionSession
Short-lived single-order token (`cs_*`) for the hosted flow. Returned once —
hand this to the frontend, never the secret key.
Unique per order — the attribution key.
Solana Pay URI (solana) or EIP-681 URI (EVM).
Fiat per 1 asset unit, decimal string.
Exact stablecoin amount the user must send.
## collectionOrders
```ts theme={null}
const order = await pulse.collectionOrders.retrieve(orderId);
const orders = await pulse.collectionOrders.list({ gate: 'naira', status: 'awaiting_payment' });
const refreshed = await pulse.collectionOrders.refreshQuote(orderId);
```
Ground truth for an order — a fallback when a webhook is missed, and the
partner-scoped listing for reconciliation. See [Orders](/backend/orders).
* **`retrieve(orderId)`** → `CollectionOrder`
* **`list(params?)`** → `Page`
* **`refreshQuote(orderId)`** → `CollectionOrder` — re-lock the quote for an
expired order on a new window; does not create a new order.
### list parameters
### Response — CollectionOrder
Offramp: where the user sends crypto. Onramp: unused (see `pay_account`).
Optional. Offramp deposit address per chain family/network when the engine
returns them, so switching chains reuses the same order. Falls back to
`deposit_address`.
Onramp: the virtual bank account to pay into. Null on offramp.
Optional; hidden if it fails to load.
Fiat to transfer (equals `target.amount`), decimal string.
On-chain detected amount — the credited figure, never the quoted one.
Provisional shape — funds detected on a network other than the order's.
Network the funds actually arrived on (may be outside the supported set).
Naira gate only; null for USD (partner omnibus).
The `list` response wraps orders in a page:
## rates.preview
```ts theme={null}
const preview = await pulse.rates.preview({ from: 'USDC', to: 'NGN', amount: '100.00' });
```
Look up the live rate without placing an order. Wraps `POST /v1/quotes` and
reshapes it for display; the returned `quoteId` proceeds to an order at the same
locked price. See [Preview a rate](/backend/preview-rate).
### Parameters — RatePreviewParams
Source currency/asset, e.g. `"USDC"`.
Destination currency, e.g. `"NGN"`.
Decimal amount in the source currency, e.g. `"100.00"`.
Uppercase engine network name.
### Response — RatePreview
Units of `to` per one unit of `from`, decimal string.
What the user parts with (equals the requested amount), decimal string.
What the user gets at this rate, decimal string.
When the locked rate expires (ISO 8601).
Pass to an order to transact at exactly this locked rate.
`rates.preview` reshapes the response to camelCase (`youSend`, `expiresAt`,
`quoteId`) for display — the only camelCase surface in the SDK. Everything else
is snake\_case on the wire.
## webhooks
```ts theme={null}
const event = pulse.webhooks.verify(rawBody, signatureHeader);
const eventOrNull = await pulse.webhooks.verifyOnce(rawBody, signatureHeader);
```
Verify a signed `Pulse-Signature` delivery and get the typed `WebhookEvent`.
`payload` MUST be the raw request body — a re-serialized JSON object will not
match the signature. See [Webhooks](/backend/webhooks) and the
[webhook event catalog](/reference/webhook-events).
Verifies the signature and replay tolerance, returns the typed event. Throws
`SignatureVerificationError` on any mismatch.
Verifies AND de-duplicates on `event.id`. First sight of an id returns the
event; a redelivery returns **`null`** (skip it, respond 200). Signature
failures still throw before the store is touched.
* `payload`: `string | Buffer` — the raw body.
* `secret`: optional; falls back to the constructor's `webhookSecret`.
* `options` (`VerifyOptions`): `toleranceSeconds` (default `300`) and `now`
(injectable Unix-seconds clock).
## Errors
Every SDK error extends `PulseError`, so `catch (e) { if (e instanceof PulseError) … }`
catches everything from the SDK.
The engine responded non-2xx. Fields: `status` (number), `code` (string),
`message` (string), `requestId` (string | null).
Network failure / timeout after the built-in retries. Field: `message`.
A credential was used where it isn't allowed — e.g. an API key constructed in
a browser. Field: `message`.
Webhook verification failed — bad signature, replay, or malformed payload.
Field: `message`.
## Types
Lowercase, product surface (sessions/orders): `ethereum`, `base`, `polygon`,
`arbitrum`, `optimism`, `celo`, `plasma`. `solana` and `ton` are recognised
but **coming soon**.
UPPERCASE, engine quote surface (`rates.preview`): `BASE`, `POLYGON`,
`ARBITRUM`, `OPTIMISM`, `ETHEREUM`, `BSC`.
`naira`, `usd`.
`USDC`, `USDT`.
`NGN`, `USD`.
`offramp`, `onramp`.
`awaiting_payment`, `deposit_detected`, `deposit_confirmed`, `converting`,
`converted_unsettled`, `completed`, `expired`, `failed`.
`pending`, `exact`, `underpaid`, `overpaid`.
**Casing matters.** `Network` (product surface, lowercase) and `EngineNetwork`
(engine quote surface, UPPERCASE) are distinct types with different members —
BSC exists only on `EngineNetwork`; solana/ton/celo/plasma only on `Network`.
Pass the one the method's signature asks for.