./docs/api

VeilNebula API API reference 0.1.0

VeilNebula accepts crypto payments over this API or through a hosted checkout page, and reports state changes over signed webhooks. Merchant identity is never verified — there is no KYC or KYB step — and the wallet half of the product is non-custodial. What a given deployment actually does depends on its configuration, so read GET /v1/services before integrating. Its `mode` field reports whether the published payment-method catalog is projected from the SANDBOX or the LIVE unit registry (PAYMENT_CATALOG_ENVIRONMENT), and its `boundaries` block reports which money paths are switched on. Deposit detection is gated by CHAIN_OBSERVATION_ENABLED. Outbound payout/refund broadcast and balance sweeps are gated by PAYOUT_BROADCAST_ENABLED, PAYOUT_SWEEP_ENABLED and SWEEP_ENABLED, all off by default; while they are off, payout and refund operations write ledger entries and emit completion webhooks without broadcasting any chain transaction. Not offered on any deployment: fiat acquiring, fiat conversion or fiat off-ramp; KYT/AML transaction screening; a contractual uptime SLA; and transaction mixing, anonymisation or any other privacy service. Blockchains are public — not asking who a merchant is does not hide who they are.

./servers

https://api.veilnebu.laDeployed API

http://localhost:4000Local API

64 operations · grouped by tag · live spec at /openapi.json.

./reference

Reference (3)

get

/health

Health check

public

Responses

200

API health status

application/jsonobject

get

/v1/exchange-rates

Get a live exchange rate

public

Parameters

Name	In	Required	Type	Description
`asset`	query	required	`$ref:AssetCode`	—
`quote`	query	required	`$ref:AssetCode`	—

Responses

200

Live provider-backed exchange-rate observation.

application/json$ref:ExchangeRate

get

/v1/services

List deployment service metadata

public

Responses

200

Supported payment methods, statuses, events, headers, and sandbox boundaries.

application/json$ref:ServiceReference

./authentication

Authentication (2)

post

/v1/auth/login

Create a merchant session

public

Request body required

application/json$ref:LoginRequest

Responses

201

Created merchant session

application/json$ref:AuthResponse

post

/v1/auth/signup

Create a merchant user, merchant, and default project

public

Request body required

application/json$ref:SignupRequest

Responses

201

Created merchant session

application/json$ref:AuthResponse

./merchant-self-service

Merchant self-service (4)

get

/v1/me

Fetch the current merchant user

merchant session

Responses

200

Current merchant user

application/json$ref:CurrentMerchantUserResponse

get

/v1/merchant/merchants/{merchantId}/projects

List projects for a merchant

merchant session

Parameters

Name	In	Required	Type	Description
`merchantId`	path	required	`string`	—

Responses

200

Projects for the merchant

application/jsonarray<$ref:MerchantProject>

post

/v1/merchant/merchants/{merchantId}/projects

Create a merchant project

merchant session

Parameters

Name	In	Required	Type	Description
`merchantId`	path	required	`string`	—

Request body required

application/json$ref:CreateMerchantProjectRequest

Responses

201

Created project

application/json$ref:MerchantProject

post

/v1/merchant/merchants/{merchantId}/projects/{projectId}/api-keys

Create a project API key

merchant session

Parameters

Name	In	Required	Type	Description
`merchantId`	path	required	`string`	—
`projectId`	path	required	`string`	—

Request body required

application/json$ref:CreateMerchantApiKeyRequest

Responses

201

Created API key

application/json$ref:CreatedMerchantApiKey

./admin-provisioning

Admin provisioning (7)

get

/v1/admin/merchants

List sandbox merchants

admin key

Responses

200

Recent merchants

application/jsonarray<$ref:Merchant>

post

/v1/admin/merchants

Create a sandbox merchant

admin key

Request body required

application/jsonobject

Responses

201

Created merchant

application/json$ref:Merchant

get

/v1/admin/merchants/{merchantId}/projects

List projects for a merchant

admin key

Parameters

Name	In	Required	Type	Description
`merchantId`	path	required	`string`	—

Responses

200

Recent projects for the merchant

application/jsonarray<$ref:Project>

post

/v1/admin/merchants/{merchantId}/projects

Create a sandbox project

admin key

Parameters

Name	In	Required	Type	Description
`merchantId`	path	required	`string`	—

Request body required

application/json$ref:CreateProjectRequest

Responses

201

Created project

application/json$ref:Project

get

/v1/admin/projects/{projectId}/api-keys

List project API keys

admin key

Parameters

Name	In	Required	Type	Description
`projectId`	path	required	`string`	—

Responses

200

Project API keys without raw secrets.

application/jsonarray<$ref:ApiKey>

post

/v1/admin/projects/{projectId}/api-keys

Create a project API key

admin key

Parameters

Name	In	Required	Type	Description
`projectId`	path	required	`string`	—

Request body required

application/json$ref:CreateApiKeyRequest

Responses

201

Created API key

application/json$ref:CreatedApiKey

post

/v1/admin/projects/{projectId}/api-keys/{apiKeyId}/revoke

Revoke a project API key

admin key

Parameters

Name	In	Required	Type	Description
`projectId`	path	required	`string`	—
`apiKeyId`	path	required	`string`	—

Responses

201

Revoked API key metadata.

application/json$ref:ApiKey

./quotes

Quotes (1)

get

/v1/quotes/fees

Preview deterministic sandbox invoice fees

ProjectApiKey

Parameters

Name	In	Required	Type	Description
`amountMinor`	query	required	`$ref:MinorAmount`	In `settlementAssetCode`'s own minor units (USDT: 6 dp, so `10000` is 0.01 USDT).
`currencyCode`	query	optional	`$ref:AssetCode`	Defaults to `settlementAssetCode`; any other value is a 400. Fee quotes never convert between currencies.
`settlementAssetCode`	query	optional	`$ref:AssetCode`	The asset the amount and every fee are written in. Defaults to USDT.
`networkCode`	query	optional	`$ref:AssetCode`	Price the quote for this exact network's own fee reserve instead of a flat default. Without it, the response's `networkMinimums` lists the minimum `amountMinor` for every live network `settlementAssetCode` resolves to.

Responses

200

Fee quote

application/json$ref:FeeQuote

./payments

Payments (5)

get

/v1/payments

List project invoices

ProjectApiKey

Responses

200

Recent invoices

application/jsonarray<$ref:Payment>

post

/v1/payments

Create a crypto invoice

ProjectApiKey

Request body required

application/json$ref:CreatePaymentRequest

Responses

201

Created invoice

application/json$ref:Payment

get

/v1/payments/page

List project invoices, cursor-paginated

ProjectApiKey

Parameters

Name	In	Required	Type	Description
`cursor`	query	optional	`string`	—
`limit`	query	optional	`integer`	—

Responses

200

One page of invoices.

application/json$ref:PaymentPageResponse

get

/v1/payments/{paymentId}

Fetch one invoice

ProjectApiKey

Parameters

Name	In	Required	Type	Description
`paymentId`	path	required	`string`	—

Responses

200

Invoice

application/json$ref:PaymentDetail

post

/v1/payments/{paymentId}/sandbox/simulate-paid

Simulate a paid sandbox invoice for the authenticated project

ProjectApiKey

Parameters

Name	In	Required	Type	Description
`paymentId`	path	required	`string`	—

Responses

201

Sandbox payment simulation recorded for the invoice

application/json$ref:MockChainTransaction

./payment-links

Payment links (7)

get

/pay/{paymentLinkId}

Fetch public reusable payment-link checkout state

public

Parameters

Name	In	Required	Type	Description
`paymentLinkId`	path	required	`string`	—

Responses

200

Reusable sandbox payment-link metadata.

application/json$ref:PublicPaymentLink

post

/pay/{paymentLinkId}

Create a sandbox invoice from a reusable payment link

public

Parameters

Name	In	Required	Type	Description
`paymentLinkId`	path	required	`string`	—

Request body

application/json$ref:CreatePaymentFromLinkRequest

Responses

201

Sandbox invoice created from the reusable payment link.

application/json$ref:PaymentLinkInvoice

get

/v1/payment-links

List reusable sandbox payment links

ProjectApiKey

Responses

200

Recent reusable sandbox payment links.

application/jsonarray<$ref:PaymentLink>

post

/v1/payment-links

Create a reusable sandbox payment link

ProjectApiKey

Request body required

application/json$ref:CreatePaymentLinkRequest

Responses

201

Created reusable sandbox payment link.

application/json$ref:PaymentLink

get

/v1/payment-links/page

List payment links, cursor-paginated

ProjectApiKey

Parameters

Name	In	Required	Type	Description
`cursor`	query	optional	`string`	—
`limit`	query	optional	`integer`	—

Responses

200

One page of payment links.

application/json$ref:PaymentLinkPageResponse

get

/v1/payment-links/{paymentLinkId}

Fetch one reusable sandbox payment link

ProjectApiKey

Parameters

Name	In	Required	Type	Description
`paymentLinkId`	path	required	`string`	—

Responses

200

Reusable sandbox payment link.

application/json$ref:PaymentLink

post

/v1/payment-links/{paymentLinkId}/disable

Disable a reusable sandbox payment link

ProjectApiKey

Parameters

Name	In	Required	Type	Description
`paymentLinkId`	path	required	`string`	—

Responses

200

Disabled reusable sandbox payment link.

application/json$ref:PaymentLink

./checkout

Checkout (2)

get

/checkout/{invoiceId}

Fetch public checkout state

public

Parameters

Name	In	Required	Type	Description
`invoiceId`	path	required	`string`	—

Responses

200

Checkout invoice, methods, and active attempt.

application/json$ref:Checkout

post

/checkout/{invoiceId}/select-method

Select a sandbox payment method

public

Parameters

Name	In	Required	Type	Description
`invoiceId`	path	required	`string`	—

Request body required

application/json$ref:SelectPaymentMethodRequest

Responses

201

Checkout state with active payment attempt.

application/json$ref:Checkout

./webhooks

Webhooks (6)

get

/v1/webhooks/deliveries

List webhook deliveries

ProjectApiKey

Parameters

Name	In	Required	Type	Description
`limit`	query	optional	`integer`	—
`invoiceId`	query	optional	`string`	Filter to deliveries for this invoice only.
`includePayload`	query	optional	`string`	Set to the exact string 'true' to include each delivery's raw signed payload, for reconciliation against your own webhook-receiver log. Omitted by default.

Responses

200

Recent deliveries.

application/jsonarray<$ref:WebhookDelivery>

post

/v1/webhooks/deliveries/run-due

Run due webhook deliveries for the authenticated project

ProjectApiKey

Responses

201

Delivery job summary for this project only.

application/json$ref:WebhookDeliverySummary

post

/v1/webhooks/deliveries/{deliveryId}/resend

Queue a resend for a terminal delivery

ProjectApiKey

Parameters

Name	In	Required	Type	Description
`deliveryId`	path	required	`string`	—

Responses

201

Fresh pending delivery.

application/json$ref:WebhookDelivery

get

/v1/webhooks/endpoints

List webhook endpoints

ProjectApiKey

Responses

200

Webhook endpoints without secrets.

application/jsonarray<$ref:WebhookEndpoint>

post

/v1/webhooks/endpoints

Create a webhook endpoint

ProjectApiKey

Request body required

application/json$ref:CreateWebhookEndpointRequest

Responses

201

Created webhook endpoint with signing secret.

application/json$ref:CreatedWebhookEndpoint

post

/v1/webhooks/endpoints/{endpointId}/test

Send a signed webhook.test delivery

ProjectApiKey

Parameters

Name	In	Required	Type	Description
`endpointId`	path	required	`string`	—

Responses

201

Delivered or queued test delivery record.

application/json$ref:WebhookDelivery

./balances

Balances (1)

get

/v1/balances

List ledger-derived balances

ProjectApiKey

Responses

200

Merchant balances.

application/json$ref:BalanceResponse

./swaps

Swaps (4)

post

/v1/swaps

Execute a sandbox balance swap

ProjectApiKey

Request body required

application/json$ref:SwapExecuteInput

Responses

201

Executed sandbox swap.

application/json$ref:SwapResult

get

/v1/swaps/page

List cursor-paginated swap history

ProjectApiKey

Parameters

Name	In	Required	Type	Description
`cursor`	query	optional	`string`	—
`limit`	query	optional	`integer`	—

Responses

200

Swap history page.

application/json$ref:SwapListPageResponse

get

/v1/swaps/quote

Quote an exact directed unit swap

ProjectApiKey

Parameters

Name	In	Required	Type	Description
`fromAsset`	query	required	`$ref:AssetCode`	—
`fromNetworkCode`	query	required	`string`	—
`toAsset`	query	required	`$ref:AssetCode`	—
`toNetworkCode`	query	required	`string`	—

Responses

200

Directed quote with exact source and target unit metadata.

application/json$ref:SwapQuote

get

/v1/swaps/units

List swap-eligible canonical units

ProjectApiKey

Responses

200

Authoritative unit catalog for the project environment.

application/json$ref:SwapUnitsResponse

./reports

Reports (6)

get

/v1/reports/balances.csv

Export ledger balances CSV

ProjectApiKey

Responses

200

CSV attachment with one row per ledger account.

text/csvstring

get

/v1/reports/payment-links.csv

Export payment links CSV

ProjectApiKey

Responses

200

CSV attachment with sandbox payment-link rows.

text/csvstring

get

/v1/reports/payments.csv

Export payments CSV

ProjectApiKey

Responses

200

CSV attachment with sandbox payment rows.

text/csvstring

get

/v1/reports/summary

Get reporting summary

ProjectApiKey

Responses

200

Reconciliation summary.

application/json$ref:ReportsSummary

get

/v1/reports/transfers.csv

Export transfers CSV

ProjectApiKey

Responses

200

CSV attachment with sandbox transfer rows.

text/csvstring

get

/v1/reports/webhooks.csv

Export webhook deliveries CSV

ProjectApiKey

Responses

200

CSV attachment with sandbox webhook delivery rows.

text/csvstring

./static-wallets

Static wallets (6)

get

/v1/static-wallets

List sandbox static wallets

ProjectApiKey

Responses

200

Recent sandbox static wallets.

application/jsonarray<$ref:StaticWallet>

post

/v1/static-wallets

Create a sandbox static wallet

ProjectApiKey

Request body required

application/json$ref:CreateStaticWalletRequest

Responses

201

Created sandbox static wallet.

application/json$ref:StaticWallet

get

/v1/static-wallets/{walletId}

Fetch one sandbox static wallet

ProjectApiKey

Parameters

Name	In	Required	Type	Description
`walletId`	path	required	`string`	—

Responses

200

Sandbox static wallet details.

application/json$ref:StaticWallet

post

/v1/static-wallets/{walletId}/block

Block a sandbox static wallet

ProjectApiKey

Parameters

Name	In	Required	Type	Description
`walletId`	path	required	`string`	—

Responses

201

Blocked sandbox static wallet.

application/json$ref:StaticWallet

get

/v1/static-wallets/{walletId}/topups

List sandbox static wallet top-ups

ProjectApiKey

Parameters

Name	In	Required	Type	Description
`walletId`	path	required	`string`	—

Responses

200

Recent completed sandbox top-ups for this static wallet.

application/jsonarray<$ref:StaticWalletTopUp>

post

/v1/static-wallets/{walletId}/unblock

Unblock a sandbox static wallet

ProjectApiKey

Parameters

Name	In	Required	Type	Description
`walletId`	path	required	`string`	—

Responses

201

Unblocked sandbox static wallet.

application/json$ref:StaticWallet

./sandbox-transfers

Sandbox transfers (6)

get

/v1/payouts

List sandbox payouts

ProjectApiKey

Responses

200

Recent sandbox payouts.

application/jsonarray<$ref:MerchantTransfer>

post

/v1/payouts

Create a simulated sandbox payout

ProjectApiKey

Request body required

application/json$ref:CreatePayoutRequest

Responses

201

Completed sandbox payout.

application/json$ref:MerchantTransfer

get

/v1/payouts/{transferId}

Fetch one sandbox payout

ProjectApiKey

Parameters

Name	In	Required	Type	Description
`transferId`	path	required	`string`	—

Responses

200

Sandbox payout.

application/json$ref:MerchantTransfer

get

/v1/refunds

List sandbox refunds

ProjectApiKey

Responses

200

Recent sandbox refunds.

application/jsonarray<$ref:MerchantTransfer>

post

/v1/refunds

Create a simulated sandbox refund

ProjectApiKey

Request body required

application/json$ref:CreateRefundRequest

Responses

201

Completed sandbox refund.

application/json$ref:MerchantTransfer

get

/v1/refunds/{transferId}

Fetch one sandbox refund

ProjectApiKey

Parameters

Name	In	Required	Type	Description
`transferId`	path	required	`string`	—

Responses

200

Sandbox refund.

application/json$ref:MerchantTransfer

./sandbox-jobs

Sandbox jobs (4)

post

/v1/admin/payment-jobs/projects/{projectId}/run-webhooks

Run due webhook delivery jobs for one project

admin key

Parameters

Name	In	Required	Type	Description
`projectId`	path	required	`string`	—

Responses

201

Job run summary.

application/json$ref:PaymentJobsSummary

post

/v1/admin/payment-jobs/run-due

Run due invoice expiry and webhook jobs

admin key

Responses

201

Job run summary.

application/json$ref:PaymentJobsSummary

post

/v1/mock-chain/static-wallet-topups

Simulate a static wallet top-up

admin key

Request body required

application/json$ref:CreateStaticWalletTopUpRequest

Responses

201

Recorded sandbox static-wallet top-up.

application/json$ref:StaticWalletTopUp

post

/v1/mock-chain/transactions

Simulate an incoming chain transaction

admin key

Request body required

application/json$ref:CreateMockChainTransactionRequest

Responses

201

Recorded mock-chain transaction.

application/json$ref:MockChainTransaction