CoinVoyage API overview

Documentation Index

Fetch the complete documentation index at: https://docs.coinvoyage.io/llms.txt

Use this file to discover all available pages before exploring further.

​

Base URL

https://api.coinvoyage.io/v2

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

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

​

Authentication

​

Public API key flows

const { data, error } = await apiClient.createDepositPayOrder({
  intent: {
    asset: {
      chain_id: ChainId.SUI,
      address: null,
    },
    amount: {
      token_amount: 10,
    },
    receiving_address: "0xYourReceivingAddress",
  },
});

​

Signed server-side flows

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

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

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

​

Where payout APIs fit

​

Where swap APIs fit

​

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 payorder_id, webhook IDs, quote IDs, or transaction hashes.
• Store token amounts exactly as returned by the API when reconciling payments. 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

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

const { data, error } = await apiClient.getPayOrder("payorder_123");

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

console.log(data.status);

​

Error handling

​

Rate limits

​

Pagination and listing

• 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 PayOrder ID rather than by page position.

​

Idempotency and retries

• Store your internal order ID in PayOrder metadata.
• Before creating a replacement PayOrder, check whether your order already has an active PayOrder.
• Treat webhook event IDs as delivery IDs and PayOrder IDs as payment lifecycle IDs.
• Make fulfillment idempotent by recording the PayOrder ID and terminal status before shipping goods, crediting balances, or updating inventory.

​

Webhook-first processing

1. Create a PayOrder from your server.
2. Store the PayOrder ID against your internal order or account.
3. Show the payment modal to the user.
4. Verify webhook signatures before parsing the event.
5. Update internal state from terminal events such as payorder_completed, payorder_refunded, payorder_expired, or payorder_error.
6. Run a scheduled reconciliation job that compares your internal state with the CoinVoyage API.

​

Go-live requirements

• 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.
• You have tested a full payment, refund, and webhook flow in the development environment.