@atumlabs/payment-gateway-client 1.0.1

package/LICENSE.md

@@ -0,0 +1,83 @@
+# ATUM LABS, INC. – PAYMENT GATEWAY CLIENT PRIVATE REPOSITORY LICENSE AGREEMENT
+**Last Updated: January 28, 2026**
+
+This Private Repository License Agreement (“Agreement”) governs your (“Licensee”) access to the Atum Labs, Inc. (“Atum”) private GitHub repository containing Atum’s proprietary source code, SDK components, documentation, and implementation examples relating to the Atum Payment Gateway Client (“Payment Gateway Client Code”).
+By accessing or using the Repository, Licensee agrees to be bound by this Agreement.
+## 1. Purpose of Access
+Atum is granting limited access to the Payment Gateway Client Code solely for the following permitted purpose (the “Authorized Purpose”):
+- Integrating, installing, operating, and testing the Payment Gateway Client in connection with Licensee's use of the Atum settlement network, Goji-facing transaction flows, and any other Atum-authorized payment operations.
+- Conducting internal audits, security review, and compliance assessments necessary to support the above operations.
+
+No other use is permitted.
+## 2. License Grant
+Subject to Licensee’s full compliance with this Agreement, Atum grants Licensee a limited, revocable, non-exclusive, non-transferable, non-sublicensable license to:
+1. Access the private GitHub repository containing the Payment Gateway Client Code (“Repository”);
+2. Download and internally use the Payment Gateway Client Code solely for the Authorized Purpose;
+3. Deploy and run compiled or interpreted versions of the Payment Gateway Client Code only within Licensee’s secure infrastructure and only for the Authorized Purpose;
+4. Create internal configuration changes or implementation wrappers necessary for integration, provided that all such modifications remain Atum Confidential Information and are disclosed to Atum upon request.
+
+No other rights are granted.
+## 3. Restrictions
+Licensee must not, and must not permit any third party to:
+1. Use the Payment Gateway Client Code for any purpose outside the Authorized Purpose;
+2. Make the Repository or any portion of the Payment Gateway Client Code available to any third party, including affiliates, without Atum’s written consent;
+3. Publicly disclose, publish, or commit any portion of the Payment Gateway Client Code to any public forum or repository;
+4. Use the Payment Gateway Client Code to build or support any competing products or networks;
+5. Reverse engineer, decompile, or otherwise attempt to derive the underlying trade secrets in the Payment Gateway Client Code (except to the limited extent permitted by applicable law);
+6. Remove or alter any proprietary notices;
+7. Use Atum’s code, data, or architecture to train or fine-tune any AI, LLM, or ML models;
+8. Use the Payment Gateway Client Code in violation of applicable law or Atum instructions.
+## 4. Ownership
+Atum retains all rights, title, and interest in and to:
+- the Payment Gateway Client Code,
+- the Repository contents,
+- the underlying architecture, algorithms, settlement workflows, and SDK components, and
+- all modifications, derivative works, feedback, or improvements.
+No ownership rights are transferred to Licensee.
+## 5. Confidentiality
+The Payment Gateway Client Code and all related documentation constitute Atum Confidential Information. Licensee must:
+1. Protect the code using industry-standard security practices;
+2. Disclose it only to employees or contractors with a legitimate need to know and who are bound by written confidentiality obligations at least as protective as this Agreement;
+3. Use it only for the Authorized Purpose;
+4. Not disclose it to any third party without Atum’s written consent;
+5. Upon termination, immediately cease use, destroy all copies (including cached or compiled forms), and certify destruction to Atum.
+
+## 6. Compliance and Security Requirements
+Licensee must comply with:
+- Atum’s security and technical standards for Payment Gateway integrations,
+- Atum’s operational procedures for network participants,
+- Key rotation, signing authority, and release-only settlement authority rules, and
+- Any written security or technical notices issued by Atum.
+
+Atum may audit Licensee’s technical implementation upon reasonable notice.
+## 7. No Warranty
+The Payment Gateway Client Code is provided “AS IS”, without any express or implied warranties. Atum does not warrant that the code will be error-free or suitable for any particular purpose.
+## 8. Limitation of Liability
+To the fullest extent permitted by law:
+- Atum will not be liable for any indirect, incidental, special, or consequential damages;
+- Atum’s total cumulative liability under this Agreement will not exceed $100.
+## 9. Term and Termination
+This Agreement is effective upon Licensee’s first access to the Repository and continues until:
+1. Terminated by either party with 10 days’ written notice;
+2. Automatically terminated if Licensee ceases to be an authorized Credit Coop participant on Atum’s network; or
+3. Automatically terminated upon any breach of Sections 2–6.
+Upon termination:
+- All rights granted hereunder immediately cease;
+- Licensee must stop using the Payment Gateway Client Code;
+- Licensee must destroy all copies and derivatives and certify destruction upon request.
+The following provisions survive termination:
+- Confidentiality (Section 5)
+- Security & Compliance Obligations (Section 6)
+- Ownership (Section 4)
+- Restrictions (Section 3)
+- No Warranty (Section 7)
+- Limitation of Liability (Section 8)
+- Governing Law (Section 10)
+- Any provisions intended by their nature to survive
+## 10. Governing Law
+Delaware law governs this Agreement.
+## 11. Entire Agreement
+This Agreement constitutes the entire agreement between the parties relating to the Payment Gateway Client Code and supersedes all prior or contemporaneous agreements specific to such access.
+
+ATUM LABS, INC.
+All rights reserved.

package/README.md

@@ -0,0 +1,247 @@
+# Payment Gateway Client
+
+TypeScript client for Atum Payment Gateway API with CLI support.
+
+> NOTE: Payments from EVM chains require prior ERC-20 approval on the source token for the Permit2 contract (0x000000000022D473030F116dDEE9F6B43aC78BA3 on virtually all EVM chains).
+> 
+> (And the same applies for Tron/TRC-20, with a Permit2 address of TJhMXTHQHeQyMD7TcKQFqAePNgG4b31H9m on mainnet or TPUqJPASUn1zLvbLBgRZ5pBYrx7WSe5ahp on Shasta)`)
+
+## Installation
+
+The package can be published to npm or to GitHub Packages (same artifact). Install
+from whichever registry it was published to.
+
+### From npm (public)
+
+```bash
+npm install @atum-labs/payment-gateway-client
+```
+
+### From GitHub Packages (private)
+
+Point the `@atum-labs` scope at GitHub's npm registry and authenticate with a
+classic personal access token that has the `read:packages` scope. Add an `.npmrc`
+in your project (or `~/.npmrc`):
+
+```
+@atum-labs:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN
+```
+
+Then `npm install @atum-labs/payment-gateway-client`. Your GitHub account must
+have been granted read access to the package.
+
+Either way this also installs the `send-payment`, `request-quote`,
+`quote-status`, and `payment-status` CLI commands.
+
+### From source (monorepo)
+
+payment-gateway-client lives inside the protocol monorepo. To work on it from source:
+
+```bash
+git clone https://github.com/Atum-Labs/protocol.git
+cd protocol
+
+# Install the workspace with pnpm. This builds payment-gateway-client and its
+# in-repo deps (km-core, turnkey-signer, solana-escrow-encoding) via the workspace:
+pnpm install
+
+# (Optional) expose the CLI globally:
+cd payment-gateway-client && pnpm link --global
+```
+
+## CLI Usage
+
+After linking, the `send-payment` command is available globally:
+
+```bash
+send-payment [options] <sender> <amount> <sourceAsset> <receiver> <destinationAsset>
+```
+
+### Arguments
+
+- `sender` - Depositor address (e.g., `0xF0D0...`)
+- `amount` - Amount to send in smallest units (e.g., `100000` for 0.10 USDC)
+- `sourceAsset` - Source asset in CAIP-19 format
+- `receiver` - Destination account address
+- `destinationAsset` - Destination asset in CAIP-19 format
+
+### Options
+
+- `-V, --version` - Output the version number
+- `--gateway <url>` - Payment gateway URL (default: testnet)
+- `--request-id <id>` - Custom request ID (overrides prefix)
+- `--request-id-prefix <prefix>` - Custom request ID prefix (default: `pmt-gw-cli`)
+- `-h, --help` - Display help
+
+### CAIP-19 Asset Format Examples
+
+- **EVM ERC20**: `eip155:42161/erc20:0xaf88d065e77c8cC2239327C5EDb3A432268e5831`
+- **Tron TRC20**: `tron:shasta/trc20:TG3XXyExBkPp9nzdajDZsozEu4BkaSJozs`
+
+### Signing provider
+
+Choose how the sender authorization is signed with `--provider` (default: `raw`).
+
+#### Private key (`--provider raw`, default)
+
+Provide your private key via environment variable:
+
+```bash
+PRIVATE_KEY=0x... send-payment <args...>
+```
+
+If not provided, you will be prompted securely.
+
+#### Turnkey (`--provider turnkey`)
+
+Sign via a Turnkey-managed wallet instead of a local private key. Set the
+Turnkey credentials in the environment; the `<sender>` argument is verified
+against the wallet's address for the source chain (a mismatch fails fast):
+
+```bash
+export TURNKEY_ORGANIZATION_ID=...
+export TURNKEY_WALLET_ID=...
+export TURNKEY_API_PUBLIC_KEY=...
+export TURNKEY_API_PRIVATE_KEY=...
+send-payment --provider turnkey <args...>
+```
+
+Turnkey signing uses the shared `@atum-labs/turnkey-signer` (and `@atum-labs/km-core`),
+which live in this monorepo under `key-management/` and are consumed as pnpm workspace
+packages (`workspace:*`), built locally by the `build:deps` step. `@solana/web3.js` and
+the other Turnkey deps are already declared, so no extra setup is required.
+
+Notes:
+- The shared packages are workspace members, so a root `pnpm install` links them, and
+  `pnpm run build` and `pnpm test` build them first (`build:deps`).
+- The Turnkey code is loaded lazily (`import('./turnkey-impl')`), so the private-key
+  path never pulls in Turnkey or `@solana/web3.js`.
+- For publishing, the build (tsup) bundles the shared `@atum-labs/*` packages directly
+  into `dist`, so the published package is self-contained with no `@atum-labs/*` runtime
+  dependencies. The siblings stay `workspace:*` devDependencies used only at build time.
+
+### Output
+
+- **PaymentRequest JSON** → `stderr` (for debugging/logging)
+- **PaymentResponse JSON** → `stdout` (for parsing/automation)
+
+### Example
+
+```bash
+PRIVATE_KEY=0xabc... send-payment \
+  0xF0D0... \
+  100000 \
+  eip155:42161/erc20:0xaf88d065e77c8cC2239327C5EDb3A432268e5831 \
+  TRX123... \
+  tron:shasta/trc20:TG3XXyExBkPp9nzdajDZsozEu4BkaSJozs
+```
+
+### Unlinking
+
+To remove the global CLI command:
+
+```bash
+npm unlink -g @atum-labs/payment-gateway-client
+```
+
+## SDK Usage
+
+### Basic Setup
+
+```typescript
+import { 
+  PaymentGatewayClient,
+  type PaymentResponse,
+  ApiError
+} from '@atum-labs/payment-gateway-client';
+import { ethers } from 'ethers';
+
+const client = new PaymentGatewayClient({
+  BASE: 'https://payment-gateway.atumlabs.xyz' // or your gateway URL
+});
+```
+
+### Example: Tron to Celo Sepolia Payment
+
+```typescript
+async function sendPayment() {
+  // Private key from environment variable
+  const privateKey = process.env.PRIVATE_KEY;
+  if (!privateKey) {
+    throw new Error('PRIVATE_KEY environment variable required');
+  }
+
+  // Tron sender address (base58 format)
+  const tronSender = 'TYourTronAddressHere';
+  
+  // Prepare the payment request
+  const paymentRequest = await client.preparePaymentRequest({
+    depositor: tronSender,
+    fulfillmentAmount: '100000', // 0.10 USDT (6 decimals)
+    sourceAsset: 'tron:shasta/trc20:TG3XXyExBkPp9nzdajDZsozEu4BkaSJozs', // USDT on Tron Shasta
+    destinationAccount: '0xYourEthereumAddressHere',
+    destinationAsset: 'eip155:11142220/erc20:0x456a3D042C0DbD3db53D5489e98dFb038553B0d0' // USDC on Celo Sepolia
+  });
+
+  // Sign the message (Tron uses the same signing as Ethereum, but without the 0x private key prefix)
+  const wallet = new ethers.Wallet(privateKey.replace(/^0x/, ''));
+  paymentRequest.sender_auth.signed_messages[0].signature = 
+    wallet.signingKey.sign(
+      paymentRequest.sender_auth.signed_messages[0].message
+    ).serialized;
+
+  try {
+    // Submit the payment
+    const response = await client.payments.submitPayment({
+      requestBody: paymentRequest
+    }) as PaymentResponse;
+
+    console.log('Payment successful!');
+    console.log('Payment ID:', response.payment_id);
+    console.log('Source TX:', response.fulfillment_confirmation?.source_tx_hash);
+    console.log('Destination TX:', response.fulfillment_confirmation?.destination_tx_hash);
+    
+    return response;
+  } catch (error) {
+    if (error instanceof ApiError) {
+      console.error('API Error:', error.status, error.statusText);
+      console.error('Response:', error.body);
+    }
+    throw error;
+  }
+}
+```
+
+### Error Handling
+
+The SDK provides detailed error information through the `ApiError` type:
+
+```typescript
+catch (error) {
+  if (error instanceof ApiError) {
+    console.error('Status:', error.status);
+    console.error('Status Text:', error.statusText);
+    console.error('URL:', error.url);
+    console.error('Response Body:', error.body);
+  }
+}
+```
+
+### Asset Identifiers
+
+Assets are identified using the [CAIP-19](https://chainagnostic.org/CAIPs/caip-19) format:
+- Format: `{chain_id}/{asset_namespace}:{asset_reference}`
+- Tron example: `tron:shasta/trc20:TG3XXyExBkPp9nzdajDZsozEu4BkaSJozs`
+- EVM example: `eip155:11142220/erc20:0x456a3D042C0DbD3db53D5489e98dFb038553B0d0`
+
+## Package Structure
+
+- `src/` - Source TypeScript files
+  - `generated/` - Auto-generated API client from OpenAPI spec
+  - `cli/` - CLI implementation
+- `dist/` - Pre-compiled JavaScript (ready to use)
+
+---
+
+This repository contains proprietary Atum Labs code. Access is restricted and governed by the Private Repository License included in this repo.

package/dist/cli/payment-status.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node