Mooncash/Documentation

DEVELOPER PLATFORM

Money movement,
without the friction.

Build payment experiences with a unified integration for fiat on-ramps and digital asset off-ramps. Start with the fundamentals, explore example requests, and adapt the integration patterns to your application.

On-ramp

Fiat currency into digital assets.

Off-ramp

Digital assets into fiat currency.

Integrations

Connect your backend and workflows.

GETTING STARTED

Your first API request.

Set up your server-side credentials and make a request from your backend. These examples use placeholder API details until you replace them with the official Mooncash contract.

Configure your environment

Keep your API key in server-side environment variables.

Create a request

Send a JSON payload to the endpoint you want to integrate.

Handle the response

Check the HTTP status, store your reference, and handle errors.

quickstart.ts

const response = await fetch(
  process.env.MOONCASH_API_BASE_URL + "/v1/on-ramp",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization:
        "Bearer " + process.env.MOONCASH_API_KEY,
    },
    body: JSON.stringify({
      amount: 10000,
      currency: "NGN",
      asset: "USDT",
      network: "TRON",
      reference: "order_12345",
      customer: {
        email: "customer@example.com",
      },
    }),
  }
);

const data = await response.json();

if (!response.ok) {
  throw new Error(
    data.message || "Unable to create payment"
  );
}

console.log(data);

This is a starter example. Confirm the actual endpoint, authentication scheme, payload fields, and response format against your implemented API.

SECURITY

Keep credentials server-side.

Your secret API key should only be used by trusted backend code. Do not place secret credentials in client-side components, browser storage, or public environment variables.

Environment variables

Store the secret key in your server environment and exclude local environment files from version control.

MOONCASH_API_BASE_URL=https://api.example.com
MOONCASH_API_KEY=your_sandbox_key

Authorization

The examples use bearer authentication as a placeholder. Replace it if your actual Mooncash API uses a different authentication mechanism.

Authorization: Bearer YOUR_API_KEY

API REFERENCE

On-ramp API.

Start a flow that converts fiat currency into a supported digital asset. The following endpoint and payload are illustrative examples, not a verified production API contract.

POST/v1/on-rampExample

Submit the amount, source currency, desired asset, network, unique reference, and customer information required by your implementation.

request.json

{
  "amount": 10000,
  "currency": "NGN",
  "asset": "USDT",
  "network": "TRON",
  "reference": "order_12345",
  "customer": {
    "email": "customer@example.com"
  }
}

Try the on-ramp example

Use a sandbox key and a configured API URL.

API REFERENCE

Off-ramp API.

Start a flow that converts a supported digital asset into fiat currency. Confirm the supported assets, networks, payout methods, and required fields before using this example.

POST/v1/off-rampExample

Include a unique transaction reference, the requested amount, asset, network, destination currency, and the customer details your API requires.

request.json

{
  "amount": 100,
  "asset": "USDT",
  "network": "TRON",
  "currency": "NGN",
  "reference": "order_12346",
  "customer": {
    "email": "customer@example.com"
  }
}

Try the off-ramp example

Use a sandbox key and a configured API URL.

INTERACTIVE TOOLS

API explorer.

Configure a request and inspect the response. This tool sends a real request to the URL you provide; it does not simulate a successful payment.

API base URLSandbox API key

POST/v1/on-ramp

Create a request for a customer to convert fiat currency into a supported digital asset.

Request body (JSON)

Only use credentials and data intended for testing. Never paste a production secret key into a browser-based tool.

TROUBLESHOOTING

Errors & responses.

Handle unsuccessful HTTP responses deliberately. The statuses below are common conventions; verify the actual error schema and status codes against the implemented Mooncash API.

400

Bad request

Check the payload format and required fields.

401

Unauthorized

Check your credentials and authentication scheme.

403

Forbidden

Check account permissions and access to the resource.

422

Validation error

Review the field-level validation details.

429

Rate limited

Apply backoff and follow the API's retry guidance.

500

Server error

Handle the failure safely and retry only when appropriate.

INTEGRATIONS

Connect your stack.

Use these starter templates to connect Mooncash to a Node.js service, a Next.js application, or a webhook endpoint. They are integration examples rather than official SDKs or verified Mooncash plugins.

mooncash.ts

import "dotenv/config";

const BASE_URL =
  process.env.MOONCASH_API_BASE_URL;

const API_KEY =
  process.env.MOONCASH_API_KEY;

if (!BASE_URL || !API_KEY) {
  throw new Error(
    "Missing Mooncash environment variables"
  );
}

export async function createOnrampPayment() {
  const response = await fetch(
    BASE_URL + "/v1/on-ramp",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: "Bearer " + API_KEY,
      },
      body: JSON.stringify({
        amount: 10000,
        currency: "NGN",
        asset: "USDT",
        network: "TRON",
        reference: "order_12345",
        customer: {
          email: "customer@example.com",
        },
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(
      data.message || "Payment request failed"
    );
  }

  return data;
}

Before using these examples

- Replace the placeholder API URL, routes, and payload fields with the actual contract.
- Implement the documented webhook signature verification before processing any event.
- Authenticate your own application users and validate payment amounts on your server.
- Make payment processing idempotent and verify transaction status with your backend.

EVENTS

Build with webhooks.

Use server-side webhook handlers to react to payment lifecycle events. The exact event names, headers, signature scheme, and retry policy must match your real Mooncash implementation.

Verify every event

Validate the webhook signature against the raw request body using the documented signing algorithm. Do not trust the payload before verification.

Handle duplicate delivery

Persist event identifiers and process each event idempotently so repeated deliveries cannot cause duplicate fulfilment.

Keep processing reliable

Acknowledge events only according to the provider's delivery contract, and use durable processing for important payment updates.

Confirm payment status

Update your internal records only after validating the event and applying the documented payment state transitions.

READY TO INTEGRATE?

Let's make money movement simpler.

Talk to our team about your use case, API integration, and the capabilities your business needs.

Contact the team