SDK quickstart

import {
  PaymentGatewayClient,
  createSenderSigner,
  signPaymentRequest,
  waitForStatus,
  assetChainId,
  getErrorResponse,
} from '@atumlabs/payment-gateway-client';

const GATEWAY_URL = 'https://payment-gw.production-testnet.atum.xyz';

const SOURCE_ASSET =
  'eip155:421614/erc20:0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d';
const DESTINATION_ASSET =
  'eip155:11142220/erc20:0x01C5C0122039549AD1493B8220cABEdD739BC44E';
const AMOUNT = '10000'; // 0.01 USDC (6 decimals)
// The most that may leave your wallet, in source USDC units: the amount plus the
// operator's charge. Size it from a quote: /get-started/get-a-price-first
const MAX_SOURCE_AMOUNT = '10101';

// Your idempotency key: names this ONE payment, so a re-attempt with the SAME
// requestId resolves onto it instead of creating a second payment. The SDK
// requires it and never generates one for you — a library-chosen id is an id you
// cannot reuse on a retry. This sample mints a fresh one per run, so each run is
// a NEW payment.
// Set REQUEST_ID to resume a payment that was interrupted while still settling:
//   REQUEST_ID=<the id printed below> npx tsx send-payment.ts
const REQUEST_ID = process.env.REQUEST_ID || `sdk-quickstart-${Date.now()}`;

async function main() {
  const privateKey = process.env.PRIVATE_KEY ?? process.env.ATUM_TESTNET_PRIVATE_KEY;
  const depositor = process.env.SENDER ?? process.env.ATUM_TESTNET_SOURCE_ADDRESS;
  const destination =
    process.env.RECEIVER ?? process.env.ATUM_TESTNET_DESTINATION_ADDRESS;

  if (!privateKey || !depositor || !destination) {
    throw new Error('Set PRIVATE_KEY, SENDER, and RECEIVER in .env');
  }

  const client = new PaymentGatewayClient({ BASE: GATEWAY_URL });

  const paymentRequest = await client.preparePaymentRequest({
    depositor,
    requestId: REQUEST_ID,
    fulfillmentAmount: AMOUNT,
    maxSourceAmount: MAX_SOURCE_AMOUNT,
    sourceAsset: SOURCE_ASSET,
    destinationAccount: destination,
    destinationAsset: DESTINATION_ASSET,
    // quoteDeadlineSeconds and fulfillmentDeadlineSeconds are optional: leave them out
    // to use the SDK defaults. For a large payment, pass a longer fulfillmentDeadlineSeconds.
    // See /get-started/concepts/deadlines#choosing-a-delivery-deadline.
  });
  console.log(`Prepared payment request (requestId: ${REQUEST_ID})`);
  console.log(`To retry this exact payment later: REQUEST_ID=${REQUEST_ID} npx tsx send-payment.ts`);

  // pinnedAddress makes the signer refuse if the key does not derive `depositor`.
  // Without it a typo signs as the wrong payer, which the gateway accepts and the
  // chain then reverts at settlement.
  // createSenderSigner takes the CAIP-2 CHAIN id, not the CAIP-19 asset id.
  // assetChainId extracts it: eip155:421614/erc20:0x75f… -> eip155:421614
  const signer = createSenderSigner(assetChainId(SOURCE_ASSET), {
    privateKey,
    pinnedAddress: depositor,
  });
  await signPaymentRequest(paymentRequest, signer);
  console.log('Signed payment authorization');

  const response = await client.payments.submitPayment({ requestBody: paymentRequest });
  console.log('Submitted payment');
  console.log(JSON.stringify(response, null, 2));

  if (!response.payment_id) {
    throw new Error('Submit response missing payment_id');
  }

  // true means this requestId already existed and you were handed the original
  // payment — nothing additional was charged.
  if (response.idempotent_replay) {
    console.log(`Replay: payment ${response.payment_id} already existed for this requestId`);
  }

  // waitForStatus keeps polling through a failed status check, which is the worst
  // moment to stop looking. With waitFor: 'finalizing' it returns once the payout is
  // mined: your recipient has the funds. `completed` follows when the payout is final,
  // which takes tens of minutes on some destination chains, so most scripts stop here.
  // If the submit response already settled it, the first check returns it.
  console.log(`Waiting on payment_id ${response.payment_id}…`);
  const outcome = await waitForStatus({
    fetchStatus: () => client.payments.getPaymentStatus({ paymentId: response.payment_id! }),
    waitFor: 'finalizing',
    budgetMs: 120_000,
  });
  console.log(JSON.stringify(outcome.snapshot, null, 2));

  // Exit codes match the CLI's, so either tool can drive the same script:
  // 0 completed (final), 5 finalizing (paid on chain, not yet final),
  // 2 still settling (NOT a failure), 3 failed or refunded,
  // 4 refund ready to submit (funds still in the settlement vault).
  if (outcome.timedOut) {
    console.log(`Still settling — re-run with REQUEST_ID=${REQUEST_ID} to resume.`);
    process.exit(2);
  }
  switch (outcome.snapshot?.status) {
    case 'completed':
      process.exit(0);
    case 'finalizing':
      console.log('Paid on chain. It becomes completed once the payout is final.');
      process.exit(5);
    case 'refund_available':
      // Not delivered. Do NOT pay again: submit refund_signature to get the funds back.
      console.log('Refund ready: submit refund_signature. See https://docs.atum.xyz/get-started/support/refunds');
      process.exit(4);
    default:
      // `failed` or `refunded`: this payment can never settle. A fresh attempt needs a NEW requestId.
      console.error(`Payment ${outcome.snapshot?.status} — this is final.`);
      process.exit(3);
  }
}

main().catch((err) => {
  // Gateway refusals carry a typed body: branch on `code`, not on the message text.
  const gatewayError = getErrorResponse(err);
  console.error(gatewayError ?? err);
  process.exit(1);
});