Quickstart - SuperCash

To start using the API, you need whitelisting from the team.Email us at support@supercash.me or
Message us on Telegram at https://supercash.me/join-tg

API Base URL

SuperCash API endpoints are hosted at: https://api.supercash.me

Prerequisites

Every API user requires a SuperCash wallet:

Sign up for a SuperCash account at https://app.supercash.me
Export your private key at https://app.supercash.me/export - this is the key you authenticate and sign payments with.
Fund the exported wallet with:
1. USDC or USDT on one of the supported chains, and
2. the chain’s native token for gas (ETH on Arbitrum/Base, BNB on BSC).
(Optional) Complete KYC at https://app.supercash.me/kyc
1. Doubles daily and monthly payment limits

1. Authenticate

All payment endpoints require Authorization: Bearer <token>. Get the token via SIWE. This token is valid for up to 7 days. Re-authenticate when it expires. The wallet you authenticate with must be the same wallet that signs the payment transaction.

Request a payload

POST /auth/payload
{ "address": "0xYourWalletAddress" }

Response:

{
  "address": "0xYourWalletAddress",
  "chainId": 56,
  "domain": "mobile.supercash.me",
  "uri": "https://mobile.supercash.me",
  "nonce": "aBc123dE",
  "statement": "Sign in to SuperCash",
  "version": "1",
  "notBefore": "2026-10-07T10:00:00.000Z"
}

Build the SIWE message and sign it (personal_sign)

import { SiweMessage } from 'siwe';
import { privateKeyToAccount } from 'viem/accounts';

const account = privateKeyToAccount('0x...');

const message = new SiweMessage({
  domain: payload.domain,
  address: payload.address,
  uri: payload.uri,
  version: payload.version,
  chainId: payload.chainId,
  nonce: payload.nonce,
  statement: payload.statement,
  issuedAt: new Date().toISOString(),
}).prepareMessage();

const signature = await account.signMessage({ message });

Exchange it for a JWT

POST /auth/login
{ "message": "<the message you signed>", "signature": "<signature>" }

Response:

{ "token": "eyJ..." }

2. Create an order

POST /v1/payment/orders
{
  "qr": "<qr string>",
  "amount": "100000",      // required only if the QR has no amount; local fiat
  "chainIds": [56]
}

Response:

{
  "data": {
    "id": "SC-8f3k2...",
    "fiatAmount": "100000",
    "fiatCurrency": "VND",
    "fiatRate": "0.0000380",
    "usdAmount": "3.80",
    "expiresAt": "2026-10-07T10:15:00.000Z",
    "routes": [
      {
        "chainId": 56,
        "token": "0x55d398326f99059fF775485246999027B3197955",
        "address": "0xf2B013591B02F51a6454aBdF6C1a7da6288575FF",
        "amount": "3800000000000000000"
      }
    ]
  }
}

Pick one route to pay with. Each route is a (chain, token) pair.
address - the recipient wallet for that chain. Differs per chain; never hardcode it.
amount - exactly what to transfer, in the token’s base units (USDC/USDT use 6 decimals on Arbitrum/Base, 18 on BSC — amount already accounts for this).
token - the ERC-20 contract to call transfer on.
The order expires at expiresAt (15 minutes). Submit the payment before then.

3. Sign the transfer

Build a regular ERC-20 transfer(route.address, route.amount) transaction on the route’s chain and sign it with your private key.

import { createWalletClient, http, encodeFunctionData } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { bsc } from 'viem/chains';

const account = privateKeyToAccount('0x...');
const walletClient = createWalletClient({
  account,
  chain: bsc,
  transport: http(process.env.BSC_RPC_URL),
});

const ERC20_ABI = [
  {
    name: 'transfer',
    type: 'function',
    stateMutability: 'nonpayable',
    inputs: [
      { name: 'to', type: 'address' },
      { name: 'amount', type: 'uint256' },
    ],
    outputs: [{ type: 'bool' }],
  },
] as const;

const signedTransaction = await walletClient.signTransaction({
  chain: bsc,
  to: route.token, // the route's token contract
  data: encodeFunctionData({
    abi: ERC20_ABI,
    functionName: 'transfer',
    args: [route.address, BigInt(route.amount)],
  }),
  account,
});

Requirements - the API validates all of these and rejects otherwise:

Signs an ERC-20 transfer of exactly route.amount base units
Recipient is exactly route.address
Token contract is the route’s token on the route’s chainId
Signed by the wallet you authenticated with

4. Submit the signed transaction

POST /v1/payment/orders/transaction
{
  "orderId": "SC-8f3k2...",
  "chainId": 56,
  "signedTransaction": "0x02f8b0..."
}

Response:

{ "data": { "hash": "0xabc123..." } }

We verify the transaction against your order’s quote, broadcast it onchain and wait for it to land. chainId must match the route you paid.

5. Poll the order status

GET /v1/payment/orders/SC-8f3k2...

Response:

{
  "data": {
    "status": "SUCCESS",
    "hash": "0xabc123...",
    "message": null,
    "expiresAt": "2026-10-07T10:15:00.000Z"
  }
}

Status	Meaning
`PENDING`	Payment submitted, not yet confirmed: keep polling
`SUCCESS`	Confirmed: fiat sent to recipient
`FAIL`	Failed: see `message` for the reason
`REFUND`	Failed after payment, crypto was refunded onchain
`TIMEOUT`	Expired without payment

Poll every 5–10 seconds until the status leaves PENDING. SUCCESS/FAIL/REFUND/TIMEOUT are terminal.

​API Base URL

​Prerequisites

​1. Authenticate

​2. Create an order

​3. Sign the transfer

​4. Submit the signed transaction

​5. Poll the order status

API Base URL

Prerequisites

1. Authenticate

2. Create an order

3. Sign the transfer

4. Submit the signed transaction

5. Poll the order status