Conversions

​

The four types

​

The flow

1. Create. POST /v1/conversions with the type, chain, the wallet that will sign, the amount and the type-specific fields. You may pass your own reference (op:<type>:<hex>, 8 to 64 hex characters or dashes after the type, so a UUID fits); otherwise ENSC mints one; a malformed reference is 400 ENSC_VALIDATION_FAILED. Re-posting a reference you already used returns the existing conversion (200), so a retried create can never double-issue. If the first attempt was cut off between the insert and the voucher (a timeout, a signer or bank-rail error), the conversion is created with lastError set, and re-posting the reference finishes it.
2. Sign. The response carries voucher: the signed authorisation, an optional approvalTransaction (an ERC-20 approve to the converter, needed when the converter must pull a token from your wallet) and transaction (the converter call). Both are { from, to, data, value: "0", chainId }: from is the wallet that must sign, to the token or the converter, value always "0". Your signer fills gas, fees and nonce; estimate gas with an explicit limit (see Signing the calldata). Send the approval first when it is present, wait for it, then send the transaction. The voucher is bound to the wallet you named and expires at voucher.expiresAt (about ten minutes); a transaction sent by another wallet or after the deadline reverts.
3. Report. Tell ENSC what happened: ensc.conversions.events.submitted(reference, txHash) once broadcast (optional but recommended), ensc.conversions.events.confirmed(reference, txHash) once mined, or ensc.conversions.events.failed(reference, error) if your wallet could not send it. You may report failed only before a transaction is recorded for the conversion (and not while it is in requires_manual_review); otherwise the answer is 409 ENSC_INVALID_STATE. On confirmed, ENSC fetches the receipt and verifies that it succeeded, that ENSC moved to or from your wallet, and that the converter emitted the event for exactly this conversion. The receipt must also be as many blocks deep as the chain’s confirmation depth requires; until it is, confirmed answers 409 ENSC_SETTLEMENT_VERIFICATION_FAILED with details.reason not_enough_confirmations and details.retriable true, so report it again shortly. Crypto legs and fiat-issue then reach succeeded; a fiat-redeem moves on to the payout.

import { EnscClient } from '@ensc/sdk';
import { executeVoucher } from '@ensc/sdk/web3';

const c = await ensc.conversions.create({
  type: 'crypto-issue',
  chain: 'celo',
  wallet,                 // the wallet that will sign; the voucher binds to it
  pair: 'USDC',
  amount: '100',
});

// Sign with the wallet's signer. executeVoucher sends the approval (if any), then the converter call.
const { transaction } = await executeVoucher(c.voucher!, signer, { rpcUrl });
const settled = await ensc.conversions.events.confirmed(c.reference, transaction.txHash);
// settled.status === 'succeeded'

​

Signing the calldata

1. Check chainId against the chain your RPC endpoint serves, and from against the account you are signing with. The voucher is bound to that wallet.
2. Estimate gas first, and send with an explicit gas limit (the estimate plus a margin). Without a limit some nodes estimate at the block gas limit and charge that much gas up front during the simulation. On Celo the native balance is also the CELO ERC-20 balance, so a crypto-issue with pair: "CELO" then reverts in simulation with transfer value exceeded balance of sender unless the wallet holds several CELO more than the amount. @ensc/sdk/web3 does this for you.
3. If the simulation fails, broadcast nothing and report events.failed(reference, error) so the conversion does not linger.
4. Send value: 0. ENSC never asks for native value.

​

Signing in the browser with a connected wallet

// Browser code. `/api/...` are routes on your own backend, which call @ensc/sdk.
import { createPublicClient, createWalletClient, custom } from 'viem';
import { celo } from 'viem/chains';

const walletClient = createWalletClient({ chain: celo, transport: custom(window.ethereum!) });
const publicClient = createPublicClient({ chain: celo, transport: custom(window.ethereum!) });
const [account] = await walletClient.requestAddresses();

// 1. Your backend calls ensc.conversions.create({ ..., wallet: account }) and returns reference and voucher.
const { reference, voucher } = await fetch('/api/conversions', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ wallet: account, pair: 'USDC', amount: '100' }),
}).then((r) => r.json());

// 2. The connected wallet signs the same { from, to, data, value, chainId } calldata.
async function send(tx: { from: `0x${string}`; to: `0x${string}`; data: `0x${string}`; chainId: number }) {
  if (tx.chainId !== (await walletClient.getChainId())) throw new Error('Switch the wallet to the conversion chain');
  if (tx.from.toLowerCase() !== account.toLowerCase()) throw new Error('Wrong wallet for this voucher');
  const estimate = await publicClient.estimateGas({ account, to: tx.to, data: tx.data, value: 0n });
  const hash = await walletClient.sendTransaction({
    account, to: tx.to, data: tx.data, value: 0n, gas: (estimate * 130n) / 100n,
  });
  const receipt = await publicClient.waitForTransactionReceipt({ hash });
  if (receipt.status !== 'success') throw new Error(`Transaction ${hash} reverted`);
  return hash;
}

if (voucher.approvalTransaction) await send(voucher.approvalTransaction);
const txHash = await send(voucher.transaction);

// 3. Your backend calls ensc.conversions.events.confirmed(reference, txHash)
//    (or events.failed(reference, error) if the wallet refused or the call reverted).
await fetch(`/api/conversions/${reference}/confirmed`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ txHash }),
});

​

Amounts and decimals

​

Type-specific fields

• crypto-issue, crypto-redeem: pair (USDC, USDT, CELO). The pair must be listed on the converter of the chain you name.
• fiat-issue: payer with email (required) and optional name and phone; the payment rail needs a contact for the collection.
• fiat-redeem: payout with bankCode, accountNumber (10 digits) and accountName. Resolve the account first with POST /v1/accounts/resolve (ensc.accounts.resolve({ bankCode, accountNumber })) and pass back the name it returns; the create refuses a name that does not match the bank record (ENSC_ACCOUNT_RESOLUTION_FAILED). Bank codes come from GET /v1/banks (ensc.banks.list()).
• Any type: counterparty (type individual or company, name, wallet) for transaction screening, and metadata (up to 16 string keys, key up to 40 and value up to 200 characters) echoed back on the conversion object only (webhook payloads carry the summary, without metadata).

// fiat-redeem: resolve the account first, then pass the name back
const { accountName } = await ensc.accounts.resolve({ bankCode, accountNumber });
const redeem = await ensc.conversions.create({
  type: 'fiat-redeem',
  chain: 'celo',
  wallet,
  amount: '150000.00',
  payout: { bankCode, accountNumber, accountName },
});

​

Paying in Naira (fiat-issue)

{
  "method": "bank_transfer",
  "bankName": "…",
  "accountNumber": "…",
  "transferAmount": "10050.00",
  "currency": "NGN",
  "expiresAt": "2026-09-15T12:30:00.000Z",
  "note": "…",
  "providerReference": "…"
}

​

Being paid in Naira (fiat-redeem)

​

Transaction screening holds

​

Vouchers that expire

​

Statuses

crypto-issue / crypto-redeem:
  created -> [screening_hold] -> voucher_issued -> onchain_submitted -> onchain_confirmed -> succeeded
fiat-issue:
  created -> [screening_hold] -> awaiting_payment -> payment_confirmed -> voucher_issued
          -> onchain_submitted -> onchain_confirmed -> succeeded
fiat-redeem:
  created -> [screening_hold] -> voucher_issued -> onchain_submitted -> onchain_confirmed
          -> payout_pending -> payout_in_progress -> payout_confirmed -> succeeded

​

The conversion object

​

Listing and pagination

• limit: page size, 1 to 200; the default is 50.
• cursor: the value of pagination.nextCursor from the previous page.

let cursor: string | undefined;
do {
  const page = await ensc.conversions.list({ status: 'requires_manual_review', limit: 100, cursor });
  for (const c of page.conversions) console.log(c.reference, c.status);
  cursor = page.pagination.hasMore ? page.pagination.nextCursor ?? undefined : undefined;
} while (cursor);

​

Webhook events

​

Error codes