Wire Transfers

This guide will walk you through the process of executing and managing wire transfers using the FSCO Wire Service API. You’ll learn how to handle fiat-to-stablecoin (on-ramp), stablecoin-to-fiat (off-ramp), and stablecoin-to-stablecoin transfers.

Overview

The Wire Service provides a bridge between traditional banking and blockchain technology, enabling seamless transfers between fiat currencies and stablecoins. Here’s what you can do with this API:

On-ramp: Convert fiat currencies (USD, EUR, etc.) to stablecoins (USDC, USDT, etc.)
Off-ramp: Convert stablecoins to fiat currencies for bank withdrawals
Transfers: Move stablecoins between wallets with currency conversion
Track: Monitor transaction status from initiation to completion
Receipt: Generate official receipts for completed transfers

Prerequisites

Before using the Wire Service API, ensure you have:

An active FSCO account with API access
API authentication credentials configured (see Authentication Guide)
Appropriate permissions for wire operations

Getting Exchange Rates

Before creating a wire transfer, you should check the current exchange rates to provide accurate information to users.

curl -X GET "https://api.fsco.io/v2/wires/rates" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const fetchRates = async () => {
  const response = await fetch('https://api.fsco.io/v2/wires/rates', {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${apiToken}`
    }
  });

  const rates = await response.json();
  console.log('Current exchange rates:', rates);
  return rates;
};

fetchRates();

import requests

def fetch_rates(api_token):
    headers = {
        'Authorization': f'Bearer {api_token}'
    }

    response = requests.get('https://api.fsco.io/v2/wires/rates', headers=headers)
    rates = response.json()

    print('Current exchange rates:', rates)
    return rates

fetch_rates(api_token)

Example Response:

[
  {
    "sourceCurrency": "USD",
    "destinationCurrency": "USDC",
    "rate": "0.995",
    "updatedAt": "2023-10-01T12:00:00Z"
  },
  {
    "sourceCurrency": "EUR",
    "destinationCurrency": "USDC",
    "rate": "1.082",
    "updatedAt": "2023-10-01T12:00:00Z"
  },
  {
    "sourceCurrency": "USDC",
    "destinationCurrency": "USDT",
    "rate": "0.999",
    "updatedAt": "2023-10-01T12:00:00Z"
  }
]

Creating a Wire Transfer

On-ramp (Fiat to Stablecoin)

To create an on-ramp wire transfer, follow these steps:

Get deposit instructions for the fiat currency
Provide these instructions to the user for bank deposit
Once the user has made the deposit, confirm it via API
Monitor the wire transfer status until completion

Step 1: Get Deposit Instructions

curl -X GET "https://api.fsco.io/v2/wires/deposit-instructions/USD" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const getDepositInstructions = async (currency) => {
  const response = await fetch(`https://api.fsco.io/v2/wires/deposit-instructions/${currency}`, {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${apiToken}`
    }
  });

  const instructions = await response.json();
  console.log('Deposit instructions:', instructions);
  return instructions;
};

getDepositInstructions('USD');

import requests

def get_deposit_instructions(api_token, currency):
    headers = {
        'Authorization': f'Bearer {api_token}'
    }

    response = requests.get(
        f'https://api.fsco.io/v2/wires/deposit-instructions/{currency}',
        headers=headers
    )

    instructions = response.json()
    print('Deposit instructions:', instructions)
    return instructions

get_deposit_instructions(api_token, 'USD')

Example Response:

{
  "currency": "USD",
  "bankName": "Example Bank",
  "accountNumber": "123456789",
  "routingNumber": "987654321",
  "iban": "US12345678901234567890",
  "swiftCode": "EXBKUS33",
  "accountHolderName": "FSCO Treasury LLC",
  "reference": "FSCO-DEP-12345",
  "instructions": "Please include the reference number in the wire transfer notes."
}

Step 2: Confirm Fiat Deposit

After the user has made a bank deposit, confirm it with the API:

curl -X POST "https://api.fsco.io/v2/wires/deposits/confirm" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "USD",
    "amount": "1000.00",
    "reference": "WIRE-12345",
    "bankName": "Example Bank",
    "walletAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "additionalDetails": {
      "senderName": "John Doe",
      "senderAccount": "987654321"
    }
  }'

const confirmDeposit = async (depositData) => {
  const response = await fetch('https://api.fsco.io/v2/wires/deposits/confirm', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(depositData)
  });

  const result = await response.json();
  console.log('Deposit confirmation result:', result);
  return result;
};

const depositData = {
  currency: 'USD',
  amount: '1000.00',
  reference: 'WIRE-12345',
  bankName: 'Example Bank',
  walletAddress: '0x1234567890abcdef1234567890abcdef12345678',
  additionalDetails: {
    senderName: 'John Doe',
    senderAccount: '987654321'
  }
};

confirmDeposit(depositData);

import requests
import json

def confirm_deposit(api_token, deposit_data):
    headers = {
        'Authorization': f'Bearer {api_token}',
        'Content-Type': 'application/json'
    }

    response = requests.post(
        'https://api.fsco.io/v2/wires/deposits/confirm',
        headers=headers,
        data=json.dumps(deposit_data)
    )

    result = response.json()
    print('Deposit confirmation result:', result)
    return result

deposit_data = {
    'currency': 'USD',
    'amount': '1000.00',
    'reference': 'WIRE-12345',
    'bankName': 'Example Bank',
    'walletAddress': '0x1234567890abcdef1234567890abcdef12345678',
    'additionalDetails': {
        'senderName': 'John Doe',
        'senderAccount': '987654321'
    }
}

confirm_deposit(api_token, deposit_data)

Off-ramp (Stablecoin to Fiat)

To create an off-ramp wire transfer (converting stablecoins to fiat):

curl -X POST "https://api.fsco.io/v2/wires" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceType": "stablecoin",
    "sourceCurrency": "USDC",
    "sourceAmount": "1000.00",
    "sourceDetails": {
      "walletAddress": "0x1234567890abcdef1234567890abcdef12345678"
    },
    "destinationType": "fiat",
    "destinationCurrency": "USD",
    "destinationDetails": {
      "bankName": "Recipient Bank",
      "accountNumber": "987654321",
      "routingNumber": "123456789",
      "accountHolderName": "Jane Doe"
    },
    "reference": "Withdrawal-54321",
    "notes": "Monthly withdrawal"
  }'

const createOffRamp = async (wireData) => {
  const response = await fetch('https://api.fsco.io/v2/wires', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(wireData)
  });

  const result = await response.json();
  console.log('Off-ramp wire created:', result);
  return result;
};

const offRampData = {
  sourceType: 'stablecoin',
  sourceCurrency: 'USDC',
  sourceAmount: '1000.00',
  sourceDetails: {
    walletAddress: '0x1234567890abcdef1234567890abcdef12345678'
  },
  destinationType: 'fiat',
  destinationCurrency: 'USD',
  destinationDetails: {
    bankName: 'Recipient Bank',
    accountNumber: '987654321',
    routingNumber: '123456789',
    accountHolderName: 'Jane Doe'
  },
  reference: 'Withdrawal-54321',
  notes: 'Monthly withdrawal'
};

createOffRamp(offRampData);

import requests
import json

def create_off_ramp(api_token, wire_data):
    headers = {
        'Authorization': f'Bearer {api_token}',
        'Content-Type': 'application/json'
    }

    response = requests.post(
        'https://api.fsco.io/v2/wires',
        headers=headers,
        data=json.dumps(wire_data)
    )

    result = response.json()
    print('Off-ramp wire created:', result)
    return result

off_ramp_data = {
    'sourceType': 'stablecoin',
    'sourceCurrency': 'USDC',
    'sourceAmount': '1000.00',
    'sourceDetails': {
        'walletAddress': '0x1234567890abcdef1234567890abcdef12345678'
    },
    'destinationType': 'fiat',
    'destinationCurrency': 'USD',
    'destinationDetails': {
        'bankName': 'Recipient Bank',
        'accountNumber': '987654321',
        'routingNumber': '123456789',
        'accountHolderName': 'Jane Doe'
    },
    'reference': 'Withdrawal-54321',
    'notes': 'Monthly withdrawal'
}

create_off_ramp(api_token, off_ramp_data)

Stablecoin-to-Stablecoin Transfer

For transferring between different stablecoins:

curl -X POST "https://api.fsco.io/v2/wires" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceType": "stablecoin",
    "sourceCurrency": "USDC",
    "sourceAmount": "1000.00",
    "sourceDetails": {
      "walletAddress": "0x1234567890abcdef1234567890abcdef12345678"
    },
    "destinationType": "stablecoin",
    "destinationCurrency": "USDT",
    "destinationDetails": {
      "walletAddress": "0xabcdef1234567890abcdef1234567890abcdef12"
    },
    "reference": "Portfolio-Rebalance-123",
    "notes": "Rebalancing stablecoin holdings"
  }'

const createStablecoinTransfer = async (wireData) => {
  const response = await fetch('https://api.fsco.io/v2/wires', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(wireData)
  });

  const result = await response.json();
  console.log('Stablecoin transfer created:', result);
  return result;
};

const transferData = {
  sourceType: 'stablecoin',
  sourceCurrency: 'USDC',
  sourceAmount: '1000.00',
  sourceDetails: {
    walletAddress: '0x1234567890abcdef1234567890abcdef12345678'
  },
  destinationType: 'stablecoin',
  destinationCurrency: 'USDT',
  destinationDetails: {
    walletAddress: '0xabcdef1234567890abcdef1234567890abcdef12'
  },
  reference: 'Portfolio-Rebalance-123',
  notes: 'Rebalancing stablecoin holdings'
};

createStablecoinTransfer(transferData);

import requests
import json

def create_stablecoin_transfer(api_token, wire_data):
    headers = {
        'Authorization': f'Bearer {api_token}',
        'Content-Type': 'application/json'
    }

    response = requests.post(
        'https://api.fsco.io/v2/wires',
        headers=headers,
        data=json.dumps(wire_data)
    )

    result = response.json()
    print('Stablecoin transfer created:', result)
    return result

transfer_data = {
    'sourceType': 'stablecoin',
    'sourceCurrency': 'USDC',
    'sourceAmount': '1000.00',
    'sourceDetails': {
        'walletAddress': '0x1234567890abcdef1234567890abcdef12345678'
    },
    'destinationType': 'stablecoin',
    'destinationCurrency': 'USDT',
    'destinationDetails': {
        'walletAddress': '0xabcdef1234567890abcdef1234567890abcdef12'
    },
    'reference': 'Portfolio-Rebalance-123',
    'notes': 'Rebalancing stablecoin holdings'
}

create_stablecoin_transfer(api_token, transfer_data)

Tracking Wire Transfers

Get a Specific Wire Transfer

curl -X GET "https://api.fsco.io/v2/wires/123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const getWireTransfer = async (wireId) => {
  const response = await fetch(`https://api.fsco.io/v2/wires/${wireId}`, {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${apiToken}`
    }
  });

  const wire = await response.json();
  console.log('Wire transfer details:', wire);
  return wire;
};

getWireTransfer('123e4567-e89b-12d3-a456-426614174000');

import requests

def get_wire_transfer(api_token, wire_id):
    headers = {
        'Authorization': f'Bearer {api_token}'
    }

    response = requests.get(
        f'https://api.fsco.io/v2/wires/{wire_id}',
        headers=headers
    )

    wire = response.json()
    print('Wire transfer details:', wire)
    return wire

get_wire_transfer(api_token, '123e4567-e89b-12d3-a456-426614174000')

Example Response:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "processing",
  "type": "on-ramp",
  "sourceType": "fiat",
  "sourceCurrency": "USD",
  "sourceAmount": "1000.00",
  "sourceDetails": {
    "bankName": "Example Bank",
    "accountNumber": "123456789",
    "accountHolderName": "John Doe"
  },
  "destinationType": "stablecoin",
  "destinationCurrency": "USDC",
  "destinationAmount": "998.50",
  "destinationDetails": {
    "walletAddress": "0x1234567890abcdef1234567890abcdef12345678"
  },
  "createdAt": "2023-10-01T12:00:00Z",
  "updatedAt": "2023-10-01T12:15:00Z",
  "completedAt": null,
  "txHashes": [],
  "externalReferences": {
    "bankReference": "REF123456"
  },
  "reference": "Invoice-12345",
  "notes": "Payment for services"
}

List Wire Transfers

curl -X GET "https://api.fsco.io/v2/wires?status=processing&fromDate=2023-09-01T00:00:00Z&page=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const listWireTransfers = async (params) => {
  const queryParams = new URLSearchParams(params).toString();
  const response = await fetch(`https://api.fsco.io/v2/wires?${queryParams}`, {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${apiToken}`
    }
  });

  const result = await response.json();
  console.log('Wire transfers:', result);
  return result;
};

const params = {
  status: 'processing',
  fromDate: '2023-09-01T00:00:00Z',
  page: 1,
  pageSize: 10
};

listWireTransfers(params);

import requests

def list_wire_transfers(api_token, params):
    headers = {
        'Authorization': f'Bearer {api_token}'
    }

    response = requests.get(
        'https://api.fsco.io/v2/wires',
        headers=headers,
        params=params
    )

    result = response.json()
    print('Wire transfers:', result)
    return result

params = {
    'status': 'processing',
    'fromDate': '2023-09-01T00:00:00Z',
    'page': 1,
    'pageSize': 10
}

list_wire_transfers(api_token, params)

View Wire Transfer History

Get the detailed history/audit trail of a wire transfer:

curl -X GET "https://api.fsco.io/v2/wires/123e4567-e89b-12d3-a456-426614174000/history" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const getWireHistory = async (wireId) => {
  const response = await fetch(`https://api.fsco.io/v2/wires/${wireId}/history`, {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${apiToken}`
    }
  });

  const history = await response.json();
  console.log('Wire history:', history);
  return history;
};

getWireHistory('123e4567-e89b-12d3-a456-426614174000');

import requests

def get_wire_history(api_token, wire_id):
    headers = {
        'Authorization': f'Bearer {api_token}'
    }

    response = requests.get(
        f'https://api.fsco.io/v2/wires/{wire_id}/history',
        headers=headers
    )

    history = response.json()
    print('Wire history:', history)
    return history

get_wire_history(api_token, '123e4567-e89b-12d3-a456-426614174000')

Example Response:

{
  "wireId": "123e4567-e89b-12d3-a456-426614174000",
  "events": [
    {
      "timestamp": "2023-10-01T12:00:00Z",
      "status": "pending",
      "description": "Wire transfer created"
    },
    {
      "timestamp": "2023-10-01T12:15:00Z",
      "status": "processing",
      "description": "Fiat deposit confirmed"
    },
    {
      "timestamp": "2023-10-01T12:25:00Z",
      "status": "processing",
      "description": "Stablecoin transfer initiated"
    }
  ]
}

Generate a Receipt

Generate a transaction receipt for a completed wire transfer:

curl -X GET "https://api.fsco.io/v2/wires/123e4567-e89b-12d3-a456-426614174000/receipt" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const generateReceipt = async (wireId) => {
  const response = await fetch(`https://api.fsco.io/v2/wires/${wireId}/receipt`, {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${apiToken}`
    }
  });

  const receipt = await response.json();
  console.log('Wire receipt:', receipt);
  return receipt;
};

generateReceipt('123e4567-e89b-12d3-a456-426614174000');

import requests

def generate_receipt(api_token, wire_id):
    headers = {
        'Authorization': f'Bearer {api_token}'
    }

    response = requests.get(
        f'https://api.fsco.io/v2/wires/{wire_id}/receipt',
        headers=headers
    )

    receipt = response.json()
    print('Wire receipt:', receipt)
    return receipt

generate_receipt(api_token, '123e4567-e89b-12d3-a456-426614174000')

Cancel a Wire Transfer

You can cancel a pending wire transfer:

curl -X POST "https://api.fsco.io/v2/wires/123e4567-e89b-12d3-a456-426614174000/cancel" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const cancelWireTransfer = async (wireId) => {
  const response = await fetch(`https://api.fsco.io/v2/wires/${wireId}/cancel`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiToken}`
    }
  });

  const result = await response.json();
  console.log('Cancellation result:', result);
  return result;
};

cancelWireTransfer('123e4567-e89b-12d3-a456-426614174000');

import requests

def cancel_wire_transfer(api_token, wire_id):
    headers = {
        'Authorization': f'Bearer {api_token}'
    }

    response = requests.post(
        f'https://api.fsco.io/v2/wires/{wire_id}/cancel',
        headers=headers
    )

    result = response.json()
    print('Cancellation result:', result)
    return result

cancel_wire_transfer(api_token, '123e4567-e89b-12d3-a456-426614174000')

Common Scenarios

Scenario 1: Corporate On-ramping

A corporation needs to convert USD to USDC for a blockchain-based payment system.

Get deposit instructions for USD
Provide these to the corporate finance team
After wire confirmation, create an on-ramp wire transfer
Track the transfer until completion
Generate a receipt for accounting records

Scenario 2: Investor Off-ramping

An investor wants to withdraw profits from stablecoin investments back to fiat currency.

Create an off-ramp wire transfer
Track the status of the wire transfer
Provide the investor with regular status updates
Generate a receipt once completed

Scenario 3: Treasury Management

A treasury department needs to rebalance stablecoin holdings across different currencies.

Check current exchange rates
Create a stablecoin-to-stablecoin transfer
Monitor the transfer status
Update internal records once completed

Handling Errors

Here are common errors you might encounter when using the Wire Service API:

400 Bad Request

Indicates invalid parameters or missing required fields. Check your request body for errors.

401 Unauthorized

Your API token is invalid or expired. Refresh your token or check your authorization.

403 Forbidden

You don’t have sufficient permissions to perform the operation.

404 Not Found

The requested wire transfer or resource doesn’t exist.

409 Conflict

Can’t perform the operation due to a conflict, such as trying to cancel a completed wire.

500 Internal Server Error

A server error occurred. Contact support if the issue persists.

Best Practices

Reference Numbers: Always include meaningful reference numbers for easier tracking
Error Handling: Implement robust error handling and retries for transient failures
Status Monitoring: Regularly poll for status updates for long-running transfers
Receipt Storage: Store receipts for completed transfers for record-keeping
Rate Checking: Always check current exchange rates before initiating transfers
Webhooks: Use webhooks to receive real-time status updates (see Webhooks Guide)

Advanced Use Cases

Bulk Transfers

For processing multiple transfers at once, you can use the batch API:

Prepare multiple wire transfer requests
Monitor the status of each transfer
Handle success and failures appropriately

Scheduled Transfers

For recurring transfers:

Create a wire transfer with your application’s scheduler
Monitor completion and set up the next scheduled transfer
Maintain records of all completed transfers

Troubleshooting

Transfer Stuck in Processing

If a transfer is stuck in the processing state:

Check the wire history to identify where the process stopped
Contact support if the transfer has been in processing for more than 24 hours
Provide the wire ID and history information when contacting support

Failed Transfers

For failed transfers:

Check the wire history to understand the reason for failure
Address the underlying issue (e.g., insufficient funds, invalid bank details)
Create a new wire transfer after resolving the issue

Next Steps

Explore the Wire API Reference for detailed endpoint documentation
Learn about Webhooks for real-time transfer status updates
Check out the Stablecoin Management guide for related stablecoin operations