On-Chain (Swap)

Move stablecoins between wallets, on the same blockchain or across blockchains.

An on-chain transfer moves stablecoins from one wallet to another, on the same blockchain or across blockchains. The Customer sends USDC on one blockchain, and Harbor sends USDC to the recipient's wallet, on the same or another blockchain.

For the supported routes, see On-Chain Coverage.

How It Works

  • You get a quote with the source and destination blockchains.
  • You create the transfer with the Customer's wallet and the recipient's wallet.
  • The response has transfer_instructions: the address the Customer sends the USDC to.
  • The Customer sends the USDC from the wallet in the transfer.
  • When the USDC arrives, Harbor sends USDC to the recipient's wallet on the destination blockchain.
sequenceDiagram
    participant App as Your App
    participant Harbor
    participant Customer
    participant Wallet as Recipient's Wallet

    App->>Harbor: POST /api/v2/transfers/quotes
    Harbor-->>App: ON_CHAIN quote
    App->>Harbor: GET /api/v2/transfers/quotes/{quote_id}/requirements
    Harbor-->>App: Transfer requirements
    App->>Harbor: POST /api/v2/transfers
    Harbor-->>App: Transfer with transfer_instructions
    Customer->>Harbor: Sends USDC to instruction_address
    Harbor->>Wallet: Sends USDC on the destination blockchain

Example: Ethereum to Solana

This example moves 100 USDC on the Ethereum network to the Customer's own wallet on Solana.

Get a Quote

Set the blockchain in source.chain and destination.chain. On-chain quotes don't need a country:

curl --location --request POST 'https://harbor-sandbox.owlpay.com/api/v2/transfers/quotes' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}' \
--data-raw '{
    "on_behalf_of": "{{CUSTOMER_UUID}}",
    "source": {
        "chain": "ethereum",
        "asset": "USDC",
        "amount": 100,
        "type": "individual"
    },
    "destination": {
        "chain": "solana",
        "asset": "USDC",
        "type": "individual"
    }
}'

The response returns one quote, with payment_method ON_CHAIN. Save its id:

{
    "data": [
        {
            "id": "quote_Nc0RB0xi5nZLVhR6SgeY1QEFWUjoVbuK4anK2gMV",
            "payment_method": "ON_CHAIN",
            "chain": "ethereum",
            "destination_chain": "solana",
            "source_amount": "100.000000",
            "source_currency": "USDC",
            "destination_amount": "95.000000",
            "destination_currency": "USDC",
            "crypto_settlement_time_min": 5,
            "crypto_settlement_time_max": 20,
            "crypto_settlement_time_unit": "MINUTES",
            "fees": [
                ...,
                {
                    "type": "BLOCKCHAIN_NETWORK_FEE",
                    "amount": "5.000000",
                    "currency": "USDC",
                    "payer": "customer",
                    "is_deducted_from_amount": true
                }
            ],
            ...
        }
    ]
}

The BLOCKCHAIN_NETWORK_FEE is deducted from the amount, so the recipient gets 95 USDC. See Commission. For all the quote fields, see Quotes.

Get the Requirements

curl --location --request GET 'https://harbor-sandbox.owlpay.com/api/v2/transfers/quotes/{{QUOTE_ID}}/requirements' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}'

For an on-chain transfer, the requirements ask for:

  • source.payment_instrument: the Customer's wallet, as an address or a Harbor wallet wallet_uuid.
  • beneficiary_info: the recipient's name and address.
  • payout_instrument.address: the recipient's wallet on the destination blockchain. For Stellar, add address_memo if the wallet needs one.
  • transfer_purpose and is_self_transfer.
  • beneficiary_receiving_wallet_type and beneficiary_institution_name: the wallet type, such as non_custodial or exchange, and the provider.

The fields change by route, so always build your request from the requirements. See Transfer Requirements.

Create the Transfer

curl --location --request POST 'https://harbor-sandbox.owlpay.com/api/v2/transfers' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}' \
--header 'X-Idempotency-Key: {{Idempotency-Key}}' \
--data-raw '{
    "quote_id": "{{QUOTE_ID}}",
    "on_behalf_of": "{{CUSTOMER_UUID}}",
    "application_transfer_uuid": "{{APPLICATION_TRANSFER_UUID}}",
    "source": {
        "payment_instrument": {
            "address": "0xae13f53f0F85FF0A2245F3c7b6bfaB18e4117b55"
        }
    },
    "destination": {
        "beneficiary_info": {
            "beneficiary_name": "Sample Customer",
            "beneficiary_address": {
                "street": "123 Main St",
                "city": "Austin",
                "state_province": "TX",
                "postal_code": "78701",
                "country": "US"
            }
        },
        "payout_instrument": {
            "address": "AYDSy8PQyRmxMgoEerPmiZ1vP3rYYN3aB2EgzCQqMgsB"
        },
        "transfer_purpose": "TRANSFER_TO_OWN_ACCOUNT",
        "is_self_transfer": true,
        "beneficiary_receiving_wallet_type": "non_custodial",
        "beneficiary_institution_name": "Phantom"
    }
}'
{
    "data": {
        "uuid": "transfer_xy1seUwiovZ7veIE78rF9pYWQKlFAcyiyz9oqU6u",
        "object": "transfer",
        "status": "pending_customer_transfer_start",
        "sub_status": null,
        "type": "swap",
        "settlement_strategy": "immediate",
        "source_received": false,
        "refund_address": null,
        "on_behalf_of": "cus_2XxcIyUQbPNzMAdyJ7NFjolt8t5zBEvqr402fjqK",
        "source": {
            "chain": "ethereum",
            "payment_instrument": {
                "address": "0xae13f53f0F85FF0A2245F3c7b6bfaB18e4117b55",
                "chain": "ethereum",
                "wallet_address": "0xae13f53f0F85FF0A2245F3c7b6bfaB18e4117b55"
            },
            "asset": "USDC",
            "amount": "100.00000000"
        },
        "destination": {
            "asset": "USDC",
            "amount": "95.00000000",
            "chain": "solana",
            "payout_instrument": {
                "chain": "solana",
                "address": "AYDSy8PQyRmxMgoEerPmiZ1vP3rYYN3aB2EgzCQqMgsB"
            },
            "is_self_transfer": true,
            "transfer_purpose": "TRANSFER_TO_OWN_ACCOUNT",
            "beneficiary_receiving_wallet_type": "non_custodial",
            "beneficiary_institution_name": "Phantom"
        },
        "application_transfer_uuid": "order-1003",
        "transfer_instructions": {
            "instruction_chain": "ethereum",
            "instruction_address": "0x99e3d05aa0f7285e40491c73cc061dae6df1fe8c",
            "instruction_memo": null
        },
        "commission": {
            "percentage": "0",
            "amount": "0"
        },
        "fees": [
            {
                "type": "HARBOR_FEE",
                "amount": "1.700000",
                "currency": "USDC",
                "charge_from": "OwlPay Harbor",
                "payer": "Your Company LLC"
            },
            {
                "type": "COMMISSION_FEE",
                "amount": "0.000000",
                "currency": "USDC",
                "charge_from": "Your Company LLC",
                "payer": "customer"
            },
            {
                "type": "BLOCKCHAIN_NETWORK_FEE",
                "amount": "5.000000",
                "currency": "USDC",
                "charge_from": "OwlPay Harbor",
                "payer": "customer"
            }
        ],
        "receipt": {
            "initial_asset": "USDC",
            "initial_amount": "100.00000000",
            "commission_fee": "0.00000000",
            "harbor_fee": "1.70",
            "final_asset": "USDC",
            "final_amount": "95.00000000",
            "exchange_rate": "0.95000000",
            "transaction_hash": null,
            "tracking_number_status": null
        },
        "meta_data": null,
        "crypto_pay_in_expired_at": "2026-10-07T09:07:59+00:00",
        "created_at": "2026-10-07T07:48:00+00:00",
        "updated_at": "2026-10-07T07:48:01+00:00"
    }
}

The transfer has type swap and starts as pending_customer_transfer_start: Harbor is waiting for the Customer's USDC.

Send the Funds

The Customer sends USDC to the address in transfer_instructions:

  • Amount: source.amount, here 100 USDC.
  • Chain and address: instruction_chain and instruction_address. If instruction_memo isn't null, include it.
  • From: the wallet in source.payment_instrument.
  • Deadline: before crypto_pay_in_expired_at. After that, the transfer expires.

metamask-send-usdc

When the USDC arrives, the transfer moves to pending_harbor, and Harbor sends the USDC on the destination blockchain. When it's sent, the transfer moves to completed. Follow the status by retrieving the transfer or with webhooks. See Transfer Lifecycle.

Confirm the Payout

When the transfer is completed, receipt.transaction_hash has the transaction on the destination blockchain. Look it up in a block explorer for that blockchain to confirm the payout:

{
    "data": {
        "uuid": "transfer_xy1seUwiovZ7veIE78rF9pYWQKlFAcyiyz9oqU6u",
        "status": "completed",
        ...,
        "receipt": {
            ...,
            "final_asset": "USDC",
            "final_amount": "95.00000000",
            "transaction_hash": "3SSMAknpVAe5f4WQun9dS3u3wCNnSwn7XQdVtUJ1frb8QDGd6mZovMmsKL6UEHPBXqu8JpewRwnvRNJK3XfvTqCi"
        }
    }
}

solana-usdc-received

The transfer.status.completed webhook has the same receipt.

Refunds

If an on-chain transfer fails after Harbor receives the stablecoin, the funds can be refunded. Set refund_address when you create the transfer, so the refund destination is known in advance:

{
    "quote_id": "{{QUOTE_ID}}",
    "on_behalf_of": "{{CUSTOMER_UUID}}",
    "application_transfer_uuid": "{{APPLICATION_TRANSFER_UUID}}",
    "source": {
        "payment_instrument": {
            "address": "0xae13f53f0F85FF0A2245F3c7b6bfaB18e4117b55"
        }
    },
    "destination": { "..." },
    "refund_address": "0xae13f53f0F85FF0A2245F3c7b6bfaB18e4117b55"
}
  • The address must be on the quote's source blockchain. The refund is sent in the same stablecoin.
  • Harbor checks the address when you create the transfer. If it isn't a valid address for that blockchain, the request returns 422 with error code 2005.
  • refund_address can't be changed through the API after the transfer is created. To use a different address, contact OwlPay Support.
  • Setting refund_address doesn't start a refund. OwlPay reviews failed transfers and sends the refund.
  • Without refund_address, the funds aren't sent back to the source address. Harbor holds them until you give OwlPay Support a refund address.
  • The full amount received is refunded. No network fee is deducted.

When the full amount is refunded, the transfer moves to refunded and Harbor sends the transfer.status.refunded webhook. To see the refund details, call GET /api/v2/transfers/{transfer_uuid}/refunds. Each refund has its amount, currency, chain, address and status. The transaction hash is in tracking_number.


Notes

  • In Sandbox, on-chain transfers run on the testnets, and Harbor really sends the USDC. You can't simulate the deposit: claim testnet USDC to your own test wallet, such as MetaMask, with the Testnet Faucet. Then send it from that wallet to instruction_address.
  • For the testnet of each blockchain, see Stablecoins and Blockchains.
  • Each blockchain has its own address format. A Solana address doesn't work on an EVM chain or on Stellar. See EVM vs. Solana vs. Stellar.
  • Overfunded: the transfer goes ahead and pays out the quoted amount only. The extra isn't refunded automatically. Contact OwlPay Support.
  • Underfunded: the transfer waits in pending_customer_transfer_start. Send the rest to the same address to continue. If it expires, contact OwlPay Support for a refund.



Did this page help you?