CoinVoyage API overview

Use the CoinVoyage API when you need direct control over order creation, quote selection, payment instructions, standalone swaps, webhook management, refunds, fee claims, off-ramp verification, bank accounts, or backend reconciliation. Most React integrations should start with the PayKit SDK, then use the API directly for server-side workflows that should never run in the browser.

Endpoint-level schemas, request bodies, and response examples are available in the generated API Reference. This page explains the conventions that apply across the API.

Base URL

Production API requests use:

https://api.coinvoyage.io/v3

SDK integrations select the base URL through the environment option:

import { ApiClient, ChainId } from "@coin-voyage/paykit/server";

const apiClient = ApiClient({
  apiKey: process.env.COIN_VOYAGE_API_KEY!,
  environment: "production",
});

Environment	Base URL	Use for
`production`	`https://api.coinvoyage.io/v3`	Live payments and settlement.
`development`	`https://acc-api.coinvoyage.io/v3`	Acceptance/integration testing.
`local`	`http://localhost:8000/v3`	Local backend development.

Authentication

CoinVoyage uses two credential types:

Credential	Where to use it	Purpose
API key	Browser or server	Identifies your organization. Safe to expose in client-side code. Sent as `X-API-KEY`.
API secret	Server only	Generates HMAC-SHA256 signatures for privileged operations. Never expose it to clients.

Signed requests use the Authorization header value:

APIKey=<apiKey>,signature=<signature>,timestamp=<timestamp>

When signing v3 requests, compute the signature over METHOD + path + timestamp, where path excludes the /v3 prefix. For example, sign POST /orders, not POST /v3/orders.

const authorization = apiClient.generateAuthorizationSignature(
  process.env.COIN_VOYAGE_API_SECRET!,
  "POST",
  "/orders"
);

Generate authorization signatures on your server only. A leaked API secret can create sales, refunds, off-ramp intents, webhooks, and fee claims for your organization.

Public API key flows

DEPOSIT orders can be created with the public API key because the recipient address is supplied by the integration and no merchant settlement configuration is modified.

const { data, error } = await apiClient.createDepositOrder({
  amount: "10",
  currency: {
    chain_id: ChainId.SUI,
    address: null,
  },
  recipient: "0xYourReceivingAddress",
});

Signed server-side flows

SALE orders, refunds, order listing, off-ramp verification, bank account management, off-ramp intents, webhook management, and fee operations require your API secret.

const { data, error } = await apiClient.createSaleOrder(
  {
    amount: "49.99",
    fiat_unit: "USD",
    metadata: {
      order_id: "order_123",
    },
  },
  process.env.COIN_VOYAGE_API_SECRET!
);

Where off-ramp APIs fit

Off-ramp verification, bank accounts, and off-ramp intents are optional. They do not replace orders, and they are not required when you only want on-chain settlement to a wallet.

API area	When to use it	Credential
Off-ramp verification	Create a hosted KYC/KYB verification link or check whether an organization is approved for fiat payout activity.	API secret
Bank accounts	Add and retrieve linked payout destinations for a verified individual or business.	API secret
Off-ramp intents	Move a supported on-chain settlement balance to a linked bank account.	API secret, plus wallet execution when required

Bank-account payouts are optional. You can bring your own externally owned account (EOA), receive funds there, and move funds anywhere you want from that wallet. Use off-ramp intents only when your product needs a CoinVoyage-managed fiat payout to a linked bank account.

See Integration flows for the end-to-end verification -> bank account -> off-ramp intent sequence.

Where swap APIs fit

Swap APIs are for standalone on-chain asset exchanges. They are separate from checkout and deposit orders: an order may use swaps internally while routing a payment, but swapQuote() and swapExecute() are useful when your product wants to quote and execute a swap as its own user action.

API area	When to use it	Credential
Swap quote	Show the expected route, output amount, and fees before the user signs.	API key
Swap execute	Create payment instructions for funding the swap.	API key, plus source-wallet signing

Request conventions

Send JSON request bodies with Content-Type: application/json.
Use ISO 8601 timestamps in UTC for stored times and event payloads.
Treat IDs as opaque strings. Do not parse structure out of order IDs, webhook IDs, quote IDs, transaction hashes, or off-ramp intent IDs.
Store token amounts exactly as returned by the API. Prefer raw string amounts for accounting systems that require exact precision.
Attach your own order, user, or invoice identifiers in metadata so webhook handlers can reconcile events without a separate lookup.

Response shape

The SDK wraps every result in APIResponse<T>:

type APIResponse<T> = {
  data?: T
  error?: {
    path: string
    statusCode: number
    status: string
    message: string
    details?: unknown
  }
}

Check error before using data:

const { data, error } = await apiClient.getOrder("order_123");

if (error) {
  console.error(error.statusCode, error.message);
  return;
}

if (!data) {
  return;
}

console.log(data.status);

Error handling

Handle API errors by status code category:

Status	Meaning	Recommended action
`400`	Invalid request parameters or path values	Show a validation error and fix the request before retrying.
`401`	Missing, invalid, or expired authentication	Check API key, signature, timestamp, and server-side secret configuration.
`403`	Credential is valid but not allowed to perform the action	Confirm organization permissions, environment, and feature access.
`404`	Resource not found	Confirm the ID belongs to the same organization and environment.
`422`	Semantically valid JSON that fails business validation	Surface the message to the operator or correct the integration mapping.
`429`	Too many requests	Back off and retry after the limit resets.
`5xx`	Temporary platform or provider error	Retry with backoff for safe operations and alert if failures persist.

For payment fulfillment, prefer webhook-driven state changes over repeated polling. Polling is useful for dashboard-style views and recovery jobs, but webhooks are the source of real-time completion signals.

Rate limits

When a request exceeds a limit, CoinVoyage returns 429 Too Many Requests. Back off instead of retrying immediately, and use the Retry-After response header when it is present. See Rate limits for retry guidance and response headers.

Pagination and listing

List endpoints return paginated data when the result set can grow over time. Use pagination for reconciliation jobs, dashboards, exports, and backfills instead of assuming a single response contains every record. When consuming paginated endpoints:

Keep the original filter set stable while walking pages.
Store the last successful cursor, page, or timestamp checkpoint for long-running jobs.
Expect new records to appear while you paginate.
Reconcile by order ID rather than by page position.

See the generated API Reference for the exact pagination parameters supported by each endpoint.

Idempotency and retries

Network requests can time out after CoinVoyage receives them. Design your integration so retrying does not create duplicate business effects:

Store your internal order ID in order metadata.
Before creating a replacement order, check whether your internal order already has an active CoinVoyage order.
Treat webhook deliveries as at-least-once events and order IDs as payment lifecycle IDs.
Make fulfillment idempotent by recording the CoinVoyage order ID and terminal status before shipping goods, crediting balances, or updating inventory.

For server retries, use exponential backoff with jitter. Retry read operations freely. Retry create or mutation operations only when your application can detect duplicates by metadata, order ID, or its own internal state.

Webhook-first processing

Production integrations should use webhooks for payment state changes:

Create an order from your server.
Store the CoinVoyage order ID against your internal order or account.
Show the payment modal to the user.
Verify webhook signatures before parsing the event.
Update internal state from terminal events such as ORDER_COMPLETED, ORDER_REFUNDED, ORDER_EXPIRED, ORDER_ERROR, or ORDER_PARTIAL_PAYMENT.
Run a scheduled reconciliation job that compares your internal state with the CoinVoyage API.

See Webhooks overview and Webhook events for delivery setup and payload examples.

Go-live requirements

Before using production credentials, confirm that:

Your API secret is stored server-side only.
Webhook signature verification is enabled.
Fulfillment is idempotent.
Failed, expired, refunded, and partial-payment states are handled.
Your settlement currency and wallet address are configured in the dashboard if you create SALE orders without explicit currency and recipient values.
You have tested a full payment, refund, and webhook flow in the intended environment.

Use the Production checklist before launch.

​Base URL

​Authentication

​Public API key flows

​Signed server-side flows

​Where off-ramp APIs fit

​Where swap APIs fit

​Request conventions

​Response shape

​Error handling

​Rate limits

​Pagination and listing

​Idempotency and retries

​Webhook-first processing

​Go-live requirements

Base URL

Authentication

Public API key flows

Signed server-side flows

Where off-ramp APIs fit

Where swap APIs fit

Request conventions

Response shape

Error handling

Rate limits

Pagination and listing

Idempotency and retries

Webhook-first processing

Go-live requirements