Wallets

Create and manage blockchain wallets for your application, and use them in transfers.

A Wallet is a blockchain address that Harbor creates and manages for your application. You can use it to receive and send stablecoins, and reference it in transfers instead of entering an address.

Wallets are custodial: Harbor holds the private keys and manages the wallet for you. You don't receive or store any keys.

Wallets belong to your Application, not to a specific Customer. To link a wallet to a record in your own system, such as one of your users, use application_reference_id.


ActionEndpoint
Create a walletPOST /api/v1/wallets
Retrieve a walletGET /api/v1/wallets/{wallet_uuid}
List all walletsGET /api/v1/wallets
Get wallet balancesGET /api/v1/wallets/{wallet_uuid}/balances
Get wallet recordsGET /api/v1/wallets/{wallet_uuid}/records
Update a walletPATCH /api/v1/wallets/{wallet_uuid}
Delete a walletDELETE /api/v1/wallets/{wallet_uuid}

⚠️

The Wallet API is currently available only to Applications registered as US-based companies. Your business operating location and company registered address must be located in a state where OwlPay holds a Money Transmitter License (MTL). See the full list of licensed states at Licenses and Disclosures.

📘

Optional Feature

The Wallet API is an optional feature and is not enabled by default. To use it, ask your Account Manager to enable it for your Application. Until it is enabled, requests return error 8002 (wallet.api_not_enabled).

Eligibility

  • Only US-based Applications can use wallets. Your business must be registered in a state where OwlPay holds a Money Transmitter License.
  • The Wallet API is not enabled by default. Ask your Account Manager to turn it on for your Application.
  • Wallets belong to your Application, not to a Customer.

Create a Wallet

POST /api/v1/wallets

Creates a wallet on the chain you choose. Harbor generates the address.

  • Required: chain. See Stablecoins and Blockchains for the supported chains.
  • Optional: description, application_reference_id and meta_data.
  • application_reference_id is your own ID for the wallet. It must be unique within your application.
💡

Sandbox Note

In the Harbor Sandbox environment (harbor-sandbox.owlpay.com), wallets are created on each chain's testnet. Addresses generated in Sandbox are only valid on these test networks. See Stablecoins and Blockchains for the testnet of each chain.

curl --location --request POST 'https://harbor-sandbox.owlpay.com/api/v1/wallets' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}' \
--header 'X-Idempotency-Key: {{Idempotency-Key}}' \
--data-raw '{
    "chain": "{{CHAIN}}",
    "description": "{{DESCRIPTION}}",
    "application_reference_id": "{{APPLICATION_REFERENCE_ID}}"
}'
{
    "data": {
        "uuid": "wallet_aX0Rlyo9CDpDMoAKVDZGvVPVajrx9HQV",
        "chain": "ethereum",
        "address": "0x76da4165da3d87b0dfcfeb867a31a0d7ab9884a5",
        "memo": null,
        "description": "Sample wallet for the docs",
        "application_reference_id": "docs-sample-001",
        "meta_data": {
            "client_name": "Deimos Pay LLC"
        },
        "visible_roles": null,
        "created_at": "2026-10-05T06:22:07.000000Z"
    }
}
  • Save the uuid. You use it to reference the wallet in other requests and in transfers.
  • memo is only used on chains that need one, such as Stellar.

Retrieve a Wallet

GET /api/v1/wallets/{wallet_uuid}

Returns one wallet. The response has the same fields as Create a Wallet.

curl --location --request GET 'https://harbor-sandbox.owlpay.com/api/v1/wallets/{{WALLET_UUID}}' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}'

List All Wallets

GET /api/v1/wallets

Returns your application's wallets, newest first, 15 per page.

Query parameterDescription
chainOnly return wallets on this chain.
pageThe page number. Defaults to 1.

curl --location --request GET 'https://harbor-sandbox.owlpay.com/api/v1/wallets?chain={{CHAIN}}&page={{PAGE}}' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}'
{
    "data": [
        {
            "uuid": "wallet_aX0Rlyo9CDpDMoAKVDZGvVPVajrx9HQV",
            "chain": "ethereum",
            "address": "0x76da4165da3d87b0dfcfeb867a31a0d7ab9884a5",
            "memo": null,
            "description": "Sample wallet for the docs",
            "application_reference_id": "docs-sample-001",
            "meta_data": {
                "client_name": "Deimos Pay LLC"
            },
            "visible_roles": null,
            "created_at": "2026-10-05T06:22:07.000000Z"
        }
    ],
    "links": {
        "first": "https://harbor-sandbox.owlpay.com/api/v1/wallets?page=1",
        "last": "https://harbor-sandbox.owlpay.com/api/v1/wallets?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://harbor-sandbox.owlpay.com/api/v1/wallets",
        "per_page": 15,
        "to": 1,
        "total": 1
    }
}
  • To get the next page, call links.next. It is null on the last page.
  • Page size is fixed at 15.

Get Wallet Balances

GET /api/v1/wallets/{wallet_uuid}/balances

Returns the balance of each asset in the wallet.

curl --location --request GET 'https://harbor-sandbox.owlpay.com/api/v1/wallets/{{WALLET_UUID}}/balances' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}'
{
    "data": [
        {
            "asset": "USDC",
            "total_amount": "100.000000",
            "locked_amount": "40",
            "available_amount": "60.000000"
        }
    ]
}
  • locked_amount: the funds you can't move yet. See Settlement and Payment Lock Time.
  • available_amount: the funds you can move. It's total_amount minus locked_amount.

Get Wallet Records

GET /api/v1/wallets/{wallet_uuid}/records

Returns the wallet's on-chain transactions, 15 per page. Like List All Wallets, the response includes links and meta for pagination.

curl --location --request GET 'https://harbor-sandbox.owlpay.com/api/v1/wallets/{{WALLET_UUID}}/records' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}'
{
    "data": [
        {
            "id": "rec_01h8yq3x7k8p9m2d4v5w6n7j8a",
            "type": "deposit",
            "from_address": "0x3f5ce5fbfe3e9af3971dd833d26ba9b5c936f0be",
            "transaction_hash": "0x4b7c1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab",
            "asset": "USDC",
            "amount": "50.000000",
            "is_locked": true,
            "lock_status": "active",
            "lock_release_at": "2026-11-03T12:00:00+00:00",
            "created_at": "2026-11-01T12:00:00+00:00",
            "updated_at": "2026-11-01T12:00:00+00:00"
        }
    ]
}
  • is_locked: true while the deposit is locked. See Settlement and Payment Lock Time.
  • lock_status: active or pending while the deposit is locked, otherwise null.
  • lock_release_at: when the lock is due to end, otherwise null.

Update a Wallet

PATCH /api/v1/wallets/{wallet_uuid}

Updates a wallet's description and application_reference_id. The chain and address can't be changed.

⚠️

Send both fields every time

Any field you leave out is cleared. For example, if you send only description, the wallet's application_reference_id is set to null. To keep a value, send it again.

curl --location --request PATCH 'https://harbor-sandbox.owlpay.com/api/v1/wallets/{{WALLET_UUID}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}' \
--header 'X-Idempotency-Key: {{Idempotency-Key}}' \
--data-raw '{
    "description": "{{DESCRIPTION}}",
    "application_reference_id": "{{APPLICATION_REFERENCE_ID}}"
}'

The response returns the updated wallet, with the same fields as Create a Wallet.

Delete a Wallet

DELETE /api/v1/wallets/{wallet_uuid}

curl --location --request DELETE 'https://harbor-sandbox.owlpay.com/api/v1/wallets/{{WALLET_UUID}}' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}'

A successful delete returns 204 No Content, with no response body.

Use a Wallet in Transfers

When you create a transfer (POST /api/v2/transfers), you can send a wallet_uuid instead of a blockchain address. Harbor fills in the wallet's address for you.

sequenceDiagram
    participant App as Your App
    participant Harbor
    participant Chain as Blockchain

    App->>Harbor: POST /api/v1/wallets
    Harbor-->>App: wallet_uuid
    App->>Harbor: POST /api/v2/transfers (wallet_uuid in source)
    Harbor->>Chain: Sends USDC from the wallet
    Chain-->>Harbor: Transaction confirmed
    Harbor-->>App: Webhook with the transfer status

On-Ramp (Fiat → Stablecoin)

Send wallet_uuid in destination.payout_instrument. This is the wallet that receives the stablecoins.

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 '{
    "on_behalf_of": "{{CUSTOMER_UUID}}",
    "quote_id": "{{QUOTE_ID}}",
    "application_transfer_uuid": "{{APPLICATION_TRANSFER_UUID}}",
    "source": {
        "payment_instrument": {
            "linked_bank_account_id": "{{LINKED_BANK_ACCOUNT_ID}}"
        }
    },
    "destination": {
        "payout_instrument": {
            "wallet_uuid": "{{WALLET_UUID}}"
        },
        "transfer_purpose": "SALARY",
        "is_self_transfer": false
    }
}'
📘

Note

When wallet_uuid is provided, Harbor fills in destination.payout_instrument.address with the wallet's address. You don't need to send the address.

Off-Ramp (Stablecoin → Fiat)

Send wallet_uuid in source.payment_instrument. This is the wallet the stablecoins are sent from.

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 '{
    "on_behalf_of": "{{CUSTOMER_UUID}}",
    "quote_id": "{{QUOTE_ID}}",
    "application_transfer_uuid": "{{APPLICATION_TRANSFER_UUID}}",
    "source": {
        "payment_instrument": {
            "wallet_uuid": "{{WALLET_UUID}}"
        }
    },
    "destination": {
        "beneficiary_info": {
            "...": "Fill according to quote requirements"
        },
        "payout_instrument": {
            "...": "Fill according to quote requirements"
        },
        "transfer_purpose": "SALARY",
        "is_self_transfer": false
    }
}'
📘

Note

When wallet_uuid is provided, Harbor fills in source.payment_instrument.address with the wallet's address. You don't need to send the address.

On-Chain (Stablecoin → Stablecoin)

Send wallet_uuid in source.payment_instrument. This is the wallet the stablecoins are sent from.

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 '{
    "on_behalf_of": "{{CUSTOMER_UUID}}",
    "quote_id": "{{QUOTE_ID}}",
    "application_transfer_uuid": "{{APPLICATION_TRANSFER_UUID}}",
    "source": {
        "payment_instrument": {
            "wallet_uuid": "{{WALLET_UUID}}"
        }
    },
    "destination": {
        "payout_instrument": {
            "chain": "{{CHAIN}}",
            "address": "{{ADDRESS}}"
        },
        "transfer_purpose": "SALARY",
        "is_self_transfer": false
    }
}'

Errors

ErrorCause
Wallet not foundThe wallet doesn't exist, or doesn't belong to your application.
Chain mismatchThe wallet's chain doesn't match the quote's chain: the source chain for off-ramp and on-chain, or the destination chain for on-ramp.

Complete Flow Diagram

sequenceDiagram
    participant App as Your App
    participant Harbor
    participant Chain as Blockchain

    Note over App,Chain: Create a wallet
    App->>Harbor: POST /api/v1/wallets
    Harbor->>Chain: Generates a wallet address
    Harbor-->>App: Wallet with uuid and address

    Note over App,Chain: Check the balances
    App->>Harbor: GET /api/v1/wallets/{wallet_uuid}/balances
    Harbor->>Chain: Reads the on-chain balances
    Harbor-->>App: Balances

    Note over App,Chain: Use the wallet in a transfer
    App->>Harbor: POST /api/v2/transfers/quotes
    Harbor-->>App: Quotes
    App->>Harbor: POST /api/v2/transfers (wallet_uuid)
    Harbor->>Harbor: Checks the wallet and chain, fills in the address
    Harbor-->>App: Transfer
    Harbor->>Chain: Sends the stablecoins

Did this page help you?