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.
| Action | Endpoint |
|---|---|
| Create a wallet | POST /api/v1/wallets |
| Retrieve a wallet | GET /api/v1/wallets/{wallet_uuid} |
| List all wallets | GET /api/v1/wallets |
| Get wallet balances | GET /api/v1/wallets/{wallet_uuid}/balances |
| Get wallet records | GET /api/v1/wallets/{wallet_uuid}/records |
| Update a wallet | PATCH /api/v1/wallets/{wallet_uuid} |
| Delete a wallet | DELETE /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_idandmeta_data. application_reference_idis 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. memois 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 parameter | Description |
|---|---|
chain | Only return wallets on this chain. |
page | The 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 isnullon 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'stotal_amountminuslocked_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:truewhile the deposit is locked. See Settlement and Payment Lock Time.lock_status:activeorpendingwhile the deposit is locked, otherwisenull.lock_release_at: when the lock is due to end, otherwisenull.
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 timeAny field you leave out is cleared. For example, if you send only
description, the wallet'sapplication_reference_idis set tonull. 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
}
}'
NoteWhen
wallet_uuidis provided, Harbor fills indestination.payout_instrument.addresswith 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
}
}'
NoteWhen
wallet_uuidis provided, Harbor fills insource.payment_instrument.addresswith 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
| Error | Cause |
|---|---|
| Wallet not found | The wallet doesn't exist, or doesn't belong to your application. |
| Chain mismatch | The 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 stablecoinsUpdated about 14 hours ago