Ghost Protocol - Bridge API Docs

Introduction

The Ghost Protocol API is a small JSON REST API over HTTPS. All responses are JSON. Amounts are in SOL. Any HTTP client works.

Base URL

https://api.veilpay.app

The same endpoints are also reachable under /api on the main site.

Authentication

The public bridge and stats endpoints require no authentication. Admin endpoints are private and are not part of the public API.

Bridge Flow

POST /bridge with an amount and the user's destination address.
The API returns a fresh depositAddress and exact depositSol.
Have the user send exactly depositSol to depositAddress.
Poll GET /bridge/:id until status becomes completed, refunded, expired, or failed.

The bridge fee is 0.5%, added on top. To bridge amountSol, the user sends depositSol = amountSol * 1.005 and receives the full amountSol.

Endpoints

GET /stats

Public network statistics.

{
  "bridges": 128,
  "volumeSol": 342.5,
  "fundingWallets": 47,
  "feeBps": 50
}

GET /bridge/amounts

The selectable bridge amounts and current fee.

{
  "amounts": [0.1, 0.5, 1, 5],
  "feeBps": 50
}

POST /bridge

Create a new bridge and get a fresh deposit address.

Field	Type	Description
amountSol	number	One of 0.1, 0.5, 1, 5. The amount the user receives.
destinationAddress	string	A valid Solana address that receives the clean payout.

curl -X POST https://api.veilpay.app/bridge \
  -H "Content-Type: application/json" \
  -d '{"amountSol": 5, "destinationAddress": "YourSolanaAddress..."}'

{
  "id": "6a5789b02410f667baad5017",
  "amountSol": 5,
  "depositSol": 5.025,
  "feeSol": 0.025,
  "depositAddress": "7EG2FMkUM87V6a9NHmUkwdZWsc1zDgLJSWSzunoX1qJs",
  "destinationAddress": "8rfY6XbZt33VJy6SPs9oWfeZdahZMhc2Z1cqRboAMhRh",
  "status": "awaiting_deposit",
  "expiresAt": "2026-07-15T14:22:56.690Z"
}

GET /bridge/:id

Fetch the current status of a bridge. Poll this until terminal.

{
  "id": "6a5789b02410f667baad5017",
  "amountSol": 5,
  "depositSol": 5.025,
  "feeSol": 0.025,
  "status": "completed",
  "depositedSol": 5.025,
  "payoutSignature": "5x8...abc",
  "refundSignature": null,
  "senderAddress": null,
  "error": null
}

Bridge Statuses

awaiting_deposit	Waiting for the user to send SOL to the deposit address.
paying_out	Deposit detected; a clean wallet is locked and payout is sent.
completed	Payout sent. See `payoutSignature`.
refunding	No clean wallet available; refund in progress.
refunded	Deposit returned. See `refundSignature`.
expired	No funds arrived before the deposit address expired.
failed	An error occurred; flagged for review.

Errors

Errors return a non-2xx status with a JSON body.

{ "error": "invalid destination address" }

400	Invalid amount or address.
404	Bridge not found.
500	Server error.