@wirexapp/wpay-baas-sdk 0.1.4 → 0.1.7

package/README.md

@@ -235,10 +235,12 @@ interface RegisterCompanyParams {
 
 | Method | Description |
 |--------|-------------|
-| `makeFullErc20Transfer(params)` | Full ERC20 transfer (two steps in one) |
-| `makeErc20TransferFirstPart(params)` | First part: create withdrawal request |
-| `makeErc20TransferFinal(callData)` | Second part: complete the transfer |
-| `makeErc20TransferSynthetic(params)` | Transfer synthetic tokens |
+| `makeErc20TransferFull(params)` | Full transfer in one call: `request(...)` → wait out the ExecutionDelayPolicy delay on-chain → submit the final execution under its custom nonce. No backend/withdrawal-request polling. |
+| `makeFullErc20Transfer(params)` | Full transfer driven by the backend: firstPart → poll withdrawal requests and wait for `valid_after` → final. Requires the Withdrawal API. |
+| `makeErc20TransferFirstPart(params)` | First part only: submit the ExecutionDelayPolicy `request(...)` (creates the withdrawal request) |
+| `makeErc20TransferFinal(callData)` | Second part only: complete the transfer with the request's calldata under its custom nonce |
+| `makeErc20TransferSynthetic(params)` | Transfer synthetic tokens directly (no unwrap, no delay policy) |
+| `makeTransferWithoutDelayPolicy(params)` | Unwrap a synthetic and transfer its base token in a single op, bypassing the ExecutionDelayPolicy. Used for the on-chain payment leg of an FX swap. |
 | `batchTransfer(params)` | Execute multiple transfers in a batch |
 
 **Transfer Parameters:**
@@ -259,6 +261,13 @@ interface BatchTransferItem {
   token: string;
   guid: string;
 }
+
+// Used by makeTransferWithoutDelayPolicy (FX swap payment leg)
+interface SwapTransferParams {
+  tokenAddress: `0x${string}`;   // wrapped synthetic token to unwrap and send (e.g. WUSD)
+  recipientAddress: `0x${string}`; // FX deposit address returned by swap.estimate
+  amount: string;                // amount of the source token (decimal string)
+}
 ```
 
 ### `sdk.crypto.yield` — Yield Service
@@ -354,6 +363,47 @@ Banking-as-a-Service module with the following sub-services:
 | `estimateCorridorTransferV2(corridor, request)` | Estimate corridor transfer (v2) |
 | `executeCorridorTransferV2(corridor, request)` | Execute corridor transfer (v2) |
 
+#### `sdk.api.baas.swap` — Swap Service (FX)
+
+Circle FX stablecoin swaps. Three-step flow: `estimate` (issues a deposit address) → on-chain payment to that address (`crypto.transfer.makeTransferWithoutDelayPolicy`) → `execute`.
+
+| Method | Description |
+|--------|-------------|
+| `estimate(request)` | Create a swap estimation and deposit address. Send exactly one of `source_asset_amount` / `destination_asset_amount`. |
+| `execute(request)` | Execute the swap after the source tokens were sent to the deposit address. |
+
+```typescript
+type SwapEstimateRequest = {
+  source_asset_address: string;      // token to swap from (e.g. USDC)
+  destination_asset_address: string; // token to receive (e.g. EURC)
+  correlation_id?: string;
+} & (
+  | { source_asset_amount: string; destination_asset_amount?: never }
+  | { destination_asset_amount: string; source_asset_amount?: never }
+);
+
+interface SwapEstimateResponse {
+  estimation_id: string;
+  destination_address: string;       // send source tokens here (preferred)
+  deposit_address: string;           // @deprecated — mirrors destination_address
+  source_asset_address: string;
+  source_asset_amount: string;
+  destination_asset_address: string;
+  destination_asset_amount: string;
+  trade_rate: string;
+  expiration_time: string;           // RFC3339, estimation expiry
+}
+
+interface SwapExecuteRequest {
+  estimation_id: string;
+  payment_transaction_hash: string;  // hash of the on-chain payment
+}
+
+interface SwapExecuteResponse {
+  trade_id: string;
+}
+```
+
 #### `sdk.api.baas.cards` — Cards Service
 
 | Method | Description |
@@ -441,11 +491,25 @@ Banking-as-a-Service module with the following sub-services:
 
 ## Examples
 
-### Full Token Transfer
+### Full Token Transfer (single call, on-chain delay)
+
+Runs the whole ExecutionDelayPolicy cycle in one call — no backend/withdrawal-request polling. `tokenAddress` must be a **synthetic** token (it is unwrapped, then its base token is transferred).
+
+```typescript
+const finalTxHash = await sdk.crypto.transfer.makeErc20TransferFull({
+  tokenAddress: '0x...', // synthetic token, e.g. WUSD
+  recipientAddress: '0x...',
+  amount: 100,
+});
+
+console.log('Final tx:', finalTxHash);
+```
+
+### Full Token Transfer (backend-driven)
 
 ```typescript
 const result = await sdk.crypto.transfer.makeFullErc20Transfer({
-  tokenAddress: '0x920D17f7A226Ce306f2B51F74a0f0dA89C3b8dF3',
+  tokenAddress: '0x...', // synthetic token, e.g. WUSD
   recipientAddress: '0x...',
   amount: 100,
 });
@@ -460,7 +524,7 @@ console.log('Success:', result.success);
 ```typescript
 // Step 1: Initiate transfer
 const txHash = await sdk.crypto.transfer.makeErc20TransferFirstPart({
-  tokenAddress: '0x920D17f7A226Ce306f2B51F74a0f0dA89C3b8dF3',
+  tokenAddress: '0x...', // synthetic token, e.g. WUSD
   recipientAddress: '0x...',
   amount: 100,
 });
@@ -483,6 +547,30 @@ const txHashes = await sdk.crypto.transfer.batchTransfer({
 });
 ```
 
+### FX Swap (estimate → pay → execute)
+
+```typescript
+// Step 1: estimate — issues a deposit address and locks a rate
+const estimate = await sdk.api.baas.swap.estimate({
+  source_asset_address: '0x...',      // e.g. USDC
+  destination_asset_address: '0x...', // e.g. EURC
+  source_asset_amount: '100',
+});
+
+// Step 2: on-chain payment to the deposit address (unwraps the synthetic, no delay policy)
+const paymentTransactionHash = await sdk.crypto.transfer.makeTransferWithoutDelayPolicy({
+  tokenAddress: '0x...', // wrapped synthetic of the source asset, e.g. WUSD
+  recipientAddress: estimate.destination_address,
+  amount: estimate.source_asset_amount,
+});
+
+// Step 3: execute — settles the swap
+const { trade_id } = await sdk.api.baas.swap.execute({
+  estimation_id: estimate.estimation_id,
+  payment_transaction_hash: paymentTransactionHash,
+});
+```
+
 ### Yield Operations
 
 ```typescript