Orders

Create an order from a quote. The response contains the customer's payment instructions. Track the order until settlement.

An onramp collects naira and delivers crypto. An offramp collects crypto and delivers naira. Both flows use the same identity fields and statuses.

Create an onramp order

Create an onramp order to collect naira through a virtual account and deliver crypto to the customer's address.

curl https://engine-api.pilot.pulseshiga.io/v1/onramp/orders \
  -H "X-API-Key: <your key>" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "partner-order-88213",
    "quote_id": "0198e2c1-…",
    "payer": {
      "name": "Ada Obi",
      "email": "ada@example.com",
      "nin": "12345678901",
      "bvn": "22345678901"
    },
    "destination": { "address": "0xAbC…" }
  }'

The response has status awaiting_payment and contains funding_account. The customer must transfer the exact funding_account.amount before the order's expires_at.

{
  "status": true,
  "data": {
    "id": "0198e2d0-…",
    "reference": "partner-order-88213",
    "type": "onramp",
    "status": "awaiting_payment",
    "rate": "1538.46",
    "source": { "currency": "NGN", "amount": "150000" },
    "destination": { "currency": "USDT", "network": "POLYGON", "amount": "97.499512" },
    "party": { "name": "Ada Obi", "email": "ada@example.com" },
    "funding_account": {
      "account_name": "Ada Obi",
      "account_number": "9901234567",
      "bank_code": "090175",
      "bank_name": "Rubies MFB",
      "amount": "150000"
    },
    "expires_at": "2026-07-30T12:12:00Z",
    "created_at": "…",
    "updated_at": "…"
  }
}

Pulse sends the crypto to destination.address on the quoted network. An invalid address returns invalid_destination_address.

The transfer must be exact

A short transfer does not fund the order. The order expires 30 minutes after the account is issued, at expires_at. You must create a new quote and order after expiry.

Create an offramp order

Create an offramp order to collect crypto through a deposit address and pay naira to a bank account. Resolve the account first, then ask the customer to confirm its registered name. See Banks.

curl https://engine-api.pilot.pulseshiga.io/v1/offramp/orders \
  -H "X-API-Key: <your key>" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "partner-order-88214",
    "quote_id": "0198e3f2-…",
    "beneficiary": {
      "name": "Ada Obi",
      "email": "ada@example.com",
      "nin": "12345678901",
      "bvn": "22345678901",
      "bank_account": {
        "bank_code": "058",
        "account_number": "0123456789"
      }
    }
  }'

The response has status awaiting_payment and contains funding_account. Send the quoted asset to funding_account.deposit_address on the quoted network, before the order's expires_at.

{
  "status": true,
  "data": {
    "id": "0198e400-…",
    "reference": "partner-order-88214",
    "type": "offramp",
    "status": "awaiting_payment",
    "rate": "1366.75",
    "source": { "currency": "USDT", "network": "POLYGON", "amount": "102.432779" },
    "destination": { "currency": "NGN", "amount": "140000" },
    "party": { "name": "Ada Obi", "email": "ada@example.com" },
    "funding_account": {
      "deposit_address": "0xDeF…",
      "network": "POLYGON"
    },
    "expires_at": "2026-07-30T12:14:00Z",
    "created_at": "…",
    "updated_at": "…"
  }
}

Order creation verifies the 10-digit account number. An unconfirmed account returns account_verification_failed without creating an order.

Pulse applies the order rate to the crypto received. The NGN payout changes with the received amount.

Send on the quoted network

Send the crypto on the same network as the quote. A deposit on the wrong chain cannot be recovered.

Every order carries an expires_at. An offramp order counts 30 minutes from creation. An onramp order counts 30 minutes from the moment its virtual account is issued, so a delayed account still gives the customer the full window.

Pulse uses the quote rate when funding arrives within 15 minutes. It can use current pricing for funding that arrives later in the window. The order API reports the effective rate and amount.

Funding that arrives after expires_at does not execute the order. Contact support to resolve a late payment.

Reference and identity

Set a reference of up to 128 characters. It must be unique across both flows and acts as the idempotency key. See Errors and retries.

The customer's National Identity Number (nin) and Bank Verification Number (bvn) are required for regulatory purposes. Each value must contain eleven digits. Pulse encrypts both at rest and omits them from API responses.

Funding instruction fields

Every order carries its funding instruction in funding_account: on create, on read, and on the order.awaiting_payment webhook. Switch on the order type before reading its shape.

For an onramp, funding_account contains account_name, account_number, bank_code, bank_name, and amount.
For an offramp, funding_account contains deposit_address and network.

The deadline is not part of the instruction. Read expires_at on the order itself.

Create and read return the same order object, so one parser serves both. The list endpoint is a summary and omits funding_account.

Order status

The API returns five order statuses.

awaiting_payment  →  processing  →  completed

Status	Meaning	Terminal
`awaiting_payment`	Waiting for the customer's naira transfer or crypto deposit.	no
`processing`	Funds received. Pulse converts and settles the funds.	no
`completed`	Settled to the destination.	yes
`expired`	Never funded in time.	yes
`failed`	Could not be settled.	yes

Track an order

Read GET /v1/orders/{id} until the status is terminal.
Wait for a webhook that carries the same milestones.

Poll with backoff while the status is not terminal. Do not poll in a tight loop.

In the test environment, use a reserved value to trigger each terminal status. See Testing.

Get one order

curl https://engine-api.pilot.pulseshiga.io/v1/orders/0198e2d0-… \
  -H "X-API-Key: <your key>"

{
  "status": true,
  "data": {
    "id": "0198e2d0-…",
    "reference": "partner-order-88213",
    "type": "onramp",
    "status": "processing",
    "rate": "1538.46",
    "source": { "currency": "NGN", "amount": "150000" },
    "destination": { "currency": "USDT", "network": "POLYGON", "amount": "97.499512" },
    "party": { "name": "Ada Obi", "email": "ada@example.com" },
    "funding_account": {
      "account_name": "Ada Obi",
      "account_number": "9901234567",
      "bank_code": "090175",
      "bank_name": "Rubies MFB",
      "amount": "150000"
    },
    "expires_at": "2026-07-30T12:12:00Z",
    "created_at": "…",
    "updated_at": "…"
  }
}

The API key scopes the request to your business. An unknown order and another business's order both return 404 order_not_found.

Order terms can differ from the quote

You must use the order's rate and destination.amount for reconciliation. Late funding can change both values. You must confirm the delivered amount from order.completed.

List orders

List orders to reconcile a period or find an order by reference. Results are ordered from newest to oldest.

curl "https://engine-api.pilot.pulseshiga.io/v1/orders?type=onramp&per_page=20" \
  -H "X-API-Key: <your key>"

{
  "status": true,
  "data": [
    {
      "id": "0198e2d0-…",
      "reference": "partner-order-88213",
      "type": "onramp",
      "status": "completed",
      "rate": "1538.46",
      "source": { "currency": "NGN", "amount": "150000" },
      "destination": { "currency": "USDT", "network": "POLYGON", "amount": "97.499512" },
      "expires_at": "2026-07-30T12:12:00Z"
    }
  ],
  "meta": { "next_cursor": "0198e2c1-…" }
}

Query parameters

Parameter	Meaning
`reference`	Your reference, exact match. Returns at most one order.
`type`	`onramp` or `offramp`.
`from`	Timestamp, inclusive lower bound (RFC 3339).
`to`	Timestamp, inclusive upper bound (RFC 3339).
`per_page`	Page size. The default is 20 and the maximum is 100.
`cursor`	The `next_cursor` from the last page.

See Pagination for cursor handling.

See the Orders reference for the full schema of every field.