Deposits and withdrawals

Prerequisites

Payward Services API credentials (see Authentication Guide)
A verified user with at least one account

Deposit addresses are issued by Payward and managed under /v1/accounts/{account_id}/funds/deposits/addresses. Withdrawals use user-added funding addresses managed under /v1/accounts/{account_id}/funds/addresses; register a destination once and pass its address_id when creating a withdrawal.

Deposits

Deposit workflow

List deposit methods

Query available deposit methods for the receiving account and asset.GET /v1/accounts/{account_id}/funds/deposits/methods/{asset_symbol}

Prepare the selected method

Fiat and crypto deposits use different preparation steps.

Fiat deposits

Bank transfer: If activation_status is needed, request activation once. If it is pending, wait and list the methods again. When it is completed, not_needed, or omitted, retrieve the bank-transfer instructions. Display every returned field so the user can make the transfer from their bank.Linked bank account: Methods with bank_link in requirements use a linked account instead of bank-transfer instructions. Link the bank account or reuse an active link, then create the deposit to request the funds. Linking alone does not move funds.

Crypto deposits

Deposit address: List existing addresses and reuse a suitable one. If none is available, claim an address. Display the address and any required tag or memo so the user can send the deposit.Bitcoin Lightning: Create an invoice for the exact BTC amount instead of claiming an address. The user must pay it before it expires.

Track the deposit

Reconcile deposits on the receiving account through GET /v1/accounts/{account_id}/portfolio/transactions?types=deposit.

The examples below use the signing helpers from the Authentication Guide. For GET requests, sign the same ordered query parameters that you send.

Addresses and memos in the examples are illustrative. Do not send funds to them.

Bank-link deposit flow

Use Create deposit to pull funds from a linked bank account through a supported deposit method. Currently supported: Plaid US (USD). Discover methods for the receiving account and asset before initiating a deposit.

List deposit methods for the receiving account and asset. Select a supported method whose requirements contains bank_link.
Complete the Bank links flow, or reuse an existing link. The account link must have status: active, and its bank link must have status: linked.
Submit the method’s id and the linked account’s account_link_id to POST /v1/accounts/{account_id}/funds/deposits. Use the same receiving account throughout the flow.

{
  "method_id": "568f754f-dcc1-43ce-bcf0-fc7262c02a5f",
  "asset_symbol": "USD",
  "amount": "10.00",
  "source": {
    "type": "account_link",
    "account_link_id": "al_123e4567-e89b-12d3-a456-426614174000"
  }
}

Replace the example identifiers with values returned by discovery and Bank Links. Authenticate the request as described in Authentication. An accepted request returns HTTP 202:

{
  "data": {
    "reference": "FTZrZD9-miDLDeq3YH1uuy0lTh18Oe"
  }
}

Acceptance does not mean settlement. Poll GET /v1/accounts/{account_id}/portfolio/transactions?types=deposit and match the returned reference to the transaction’s reference.id. The Portfolio transaction id is a separate identifier. Bank-link deposits return a reference.

Create deposit is not idempotent. Do not automatically retry after a timeout or an ambiguous error: the deposit may already have been initiated. Check the account’s transactions and contact Payward Services support if the outcome remains unclear.

Step 1: list deposit methods

Query available deposit methods for an asset. Use the method’s id as method_id when listing deposit destinations or claiming a crypto address. Check requirements on the selected method:

[]: no additional requirements are reported. Follow the applicable activation and deposit-instructions steps.
["bank_link"]: a linked bank account is required. If you do not already have a suitable link, use Create bank link with the returned method id as method_id, then send the user through the hosted linking flow.

This is a method requirement, not the user’s linking status. It remains bank_link even when the user already has a linked account. Do not infer the requirement from the method name or supports_virtual_accounts. Example USD method excerpts:

[
  { "network": "Cross River Bank (Wire)", "requirements": [] },
  { "network": "Plaid US", "requirements": ["bank_link"] }
]

For fiat methods, continue when activation_status is not_needed or completed, or when the field is omitted. When it is needed, activate the method once in Step 2. When it is pending, do not send another activation request; list the methods again later or offer another usable method.

Most cryptocurrency deposits are free, with minimum deposit amounts varying by asset. A few cryptocurrencies are charged an address_setup_fee (a one-time fee on the user’s first deposit to a new address) or a per-deposit fee.

def list_deposit_methods(account_id, asset_symbol):
    endpoint = f"/v1/accounts/{account_id}/funds/deposits/methods/{asset_symbol}"

    nonce = time.time_ns()
    signature = get_payward_signature(endpoint, None, API_SECRET, nonce)

    headers = {
        "API-Key": API_KEY,
        "API-Nonce": str(nonce),
        "API-Sign": signature,
    }

    response = requests.get(
        f"{BASE_URL}{endpoint}",
        headers=headers,
    )
    return response.json()


methods = list_deposit_methods(account_id, "BTC")
for m in methods["data"]:
    print(f"{m['network']} (id: {m['id']})")

async function listDepositMethods(accountId, assetSymbol) {
  const endpoint = `/v1/accounts/${accountId}/funds/deposits/methods/${assetSymbol}`;

  const nonce = process.hrtime.bigint().toString();
  const signature = getPaywardSignature(endpoint, null, API_SECRET, nonce);

  const response = await fetch(`${BASE_URL}${endpoint}`, {
    method: 'GET',
    headers: {
      'API-Key': API_KEY,
      'API-Nonce': nonce,
      'API-Sign': signature,
    },
  });

  return response.json();
}

const methods = await listDepositMethods(accountId, 'BTC');
for (const m of methods.data) {
  console.log(`${m.network} (id: ${m.id})`);
}

Use page_token from next_page_token to request the next page. Omit it for the first page.

Response example

{
  "data": [
    {
      "id": "2fa11f79-eeba-4d4e-afda-029abff6e29e",
      "network": "Bitcoin",
      "requirements": [],
      "network_info": {
        "explorer": "https://mempool.space/tx/",
        "confirmations": "3",
        "est_confirmation_time": "45"
      },
      "minimum": {
        "symbol": "BTC",
        "name": "Bitcoin",
        "type": "crypto",
        "amount": "0.0001"
      }
    }
  ]
}

Key fields to display to users are network, method when present, fee, minimum, activation_status, and network_info.est_confirmation_time. Pass the method’s id back as method_id when activating a method, listing deposit instructions, or claiming a crypto address. Optional fee, limit, and network fields are omitted when they do not apply.

For fiat methods, supports_virtual_accounts: true means Funding can provide dedicated virtual-account instructions. false does not identify a particular alternative flow, and omission means Funding did not return deposit metadata for the method. Use the deposit-instructions response, not this boolean, to determine which banking fields and payment reference are available.

Crypto assets can have a maximum of five deposit addresses. Some crypto funding methods share an address space, so the same address can be returned for different assets or networks. method_id selects a context in which the returned address is valid; it does not say how the address was originally claimed. List and reuse an existing address before claiming another.

Step 2: activate a deposit method when required

If the selected method’s activation_status is needed, request activation using its id as method_id. A 204 response means Funding accepted the request; it does not mean activation has necessarily completed, and it does not contain deposit instructions.

def activate_deposit_method(account_id, method_id):
    endpoint = (
        f"/v1/accounts/{account_id}/funds/deposits/methods/"
        f"{method_id}/activation"
    )

    nonce = time.time_ns()
    signature = get_payward_signature(endpoint, None, API_SECRET, nonce)

    headers = {
        "API-Key": API_KEY,
        "API-Nonce": str(nonce),
        "API-Sign": signature,
    }

    response = requests.post(
        f"{BASE_URL}{endpoint}",
        headers=headers,
    )
    response.raise_for_status()


activate_deposit_method(
    account_id,
    "5e764f4c-f924-47f0-9fcb-6f98c37d1575",
)

async function activateDepositMethod(accountId, methodId) {
  const endpoint = `/v1/accounts/${accountId}/funds/deposits/methods/${methodId}/activation`;

  const nonce = process.hrtime.bigint().toString();
  const signature = getPaywardSignature(endpoint, null, API_SECRET, nonce);

  const response = await fetch(`${BASE_URL}${endpoint}`, {
    method: 'POST',
    headers: {
      'API-Key': API_KEY,
      'API-Nonce': nonce,
      'API-Sign': signature,
    },
  });

  if (!response.ok) {
    throw new Error(`Activation failed with status ${response.status}`);
  }
}

await activateDepositMethod(accountId, '5e764f4c-f924-47f0-9fcb-6f98c37d1575');

After the request is accepted, list deposit methods again. Continue to Step 3 when the selected method reports completed. If it reports pending, wait and list the methods again later.

Activation returns 400 Bad Request when the selected account is missing verification information or documents required by the funding method. The error is associated with account_id; when available, its message names the missing requirement, such as address.

If the activation request times out or its outcome is unclear, list the deposit methods again before taking further action. Do not retry if the activation status is pending or completed.

Step 3: list deposit addresses

Retrieve the crypto addresses or fiat bank-transfer instructions available for the selected funding method. Reuse a returned crypto address instead of creating a new one each time.

def list_deposit_addresses(account_id, method_id, page_token=None):
    endpoint = f"/v1/accounts/{account_id}/funds/deposits/addresses"

    params = {
        "method_id": method_id,
    }
    if page_token:
        params["page_token"] = page_token

    nonce = time.time_ns()
    signature = get_payward_signature(endpoint, None, API_SECRET, nonce, params)

    headers = {
        "API-Key": API_KEY,
        "API-Nonce": str(nonce),
        "API-Sign": signature,
    }

    response = requests.get(
        f"{BASE_URL}{endpoint}",
        headers=headers,
        params=params,
    )
    return response.json()


addresses = list_deposit_addresses(
    account_id, "2fa11f79-eeba-4d4e-afda-029abff6e29e"
)
for item in addresses["data"]:
    details = item["address_details"]
    if "crypto" in details:
        crypto = details["crypto"]
        print(f"Crypto address: {crypto['address']}")
    else:
        fiat = details["fiat"]
        print(f"Fiat instructions: {fiat}")

async function listDepositAddresses(accountId, methodId, pageToken = null) {
  const endpoint = `/v1/accounts/${accountId}/funds/deposits/addresses`;

  const params = { method_id: methodId };
  if (pageToken) params.page_token = pageToken;

  const nonce = process.hrtime.bigint().toString();
  const signature = getPaywardSignature(endpoint, null, API_SECRET, nonce, params);

  const searchParams = new URLSearchParams(params);
  const url = `${BASE_URL}${endpoint}?${searchParams.toString()}`;
  const response = await fetch(url, {
    method: 'GET',
    headers: {
      'API-Key': API_KEY,
      'API-Nonce': nonce,
      'API-Sign': signature,
    },
  });

  return response.json();
}

const addresses = await listDepositAddresses(accountId, '2fa11f79-eeba-4d4e-afda-029abff6e29e');
for (const item of addresses.data) {
  if (item.address_details.crypto) {
    console.log('Crypto address:', item.address_details.crypto.address);
  } else {
    console.log('Fiat instructions:', item.address_details.fiat);
  }
}

Response example

{
  "data": [
    {
      "address_details": {
        "crypto": {
          "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
        }
      },
      "expire_time": "2026-08-11T09:20:00Z"
    },
    {
      "address_details": {
        "fiat": {
          "bank": "Banking Circle",
          "iban": "GB29NWBK60161331926819",
          "bic": "NWBKGB2L",
          "name_on_account": "Payward Ltd",
          "reference": "AA71 N84G 7JER CJPQ"
        }
      }
    }
  ]
}

Every item has one address_details variant:

crypto.address is required for crypto destinations. crypto.tag and crypto.memo are present only when the network requires them.
The fiat object contains only the banking fields that apply to the selected method. Fields such as iban, account_number, routing_number, sort_code, bic, swift, name_on_account, and reference are optional individually. When reference is present, include it with the fiat deposit.
expire_time is present only when the destination expires.

Use page_token from next_page_token to retrieve the next page.

Completed deposits appear in GET /v1/accounts/{account_id}/portfolio/transactions?types=deposit. Portfolio visibility is asynchronous.

Step 4: claim a crypto deposit address

If Step 3 returns no suitable crypto address, claim one using the method id from Step 1 as method_id. Fiat deposit methods return their instructions from Step 3 and cannot be claimed with this operation.

You can claim a maximum of five deposit addresses per asset. List the account’s existing addresses before claiming another one.

import json


def claim_deposit_address(account_id, method_id):
    endpoint = f"/v1/accounts/{account_id}/funds/deposits/addresses"
    body = json.dumps({"method_id": method_id}, separators=(",", ":"))
    nonce = time.time_ns()
    signature = get_payward_signature(endpoint, body, API_SECRET, nonce)

    headers = {
        "API-Key": API_KEY,
        "API-Nonce": str(nonce),
        "API-Sign": signature,
        "Content-Type": "application/json",
    }

    response = requests.post(
        f"{BASE_URL}{endpoint}",
        headers=headers,
        data=body,
    )
    return response.json()


address = claim_deposit_address(
    account_id,
    "2fa11f79-eeba-4d4e-afda-029abff6e29e",
)
print(f"Deposit address: {address['data']['address']}")

async function claimDepositAddress(accountId, methodId) {
  const endpoint = `/v1/accounts/${accountId}/funds/deposits/addresses`;
  const body = JSON.stringify({ method_id: methodId });
  const nonce = process.hrtime.bigint().toString();
  const signature = getPaywardSignature(endpoint, body, API_SECRET, nonce);

  const response = await fetch(`${BASE_URL}${endpoint}`, {
    method: 'POST',
    headers: {
      'API-Key': API_KEY,
      'API-Nonce': nonce,
      'API-Sign': signature,
      'Content-Type': 'application/json',
    },
    body,
  });

  return response.json();
}

const address = await claimDepositAddress(accountId, '2fa11f79-eeba-4d4e-afda-029abff6e29e');
console.log('Deposit address:', address.data.address);

{
  "data": {
    "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
  }
}

Address claims are not idempotent. Do not retry automatically after a timeout or another response with an unknown outcome. List the account’s addresses before deciding whether to make another claim.

Some networks (e.g., XRP, XLM) require a tag or memo in addition to the address. If tag or memo is present in the response, your UI must display it and instruct the user to include it when sending funds. Deposits sent without the required tag/memo may be lost.

Bitcoin Lightning invoice flow

For the Bitcoin Lightning deposit method, create a BOLT11 invoice for the exact BTC amount the user intends to deposit. Use the limits from the deposit-methods response to validate the amount before requesting the invoice. The selected account_id is the account that receives the completed deposit.

def create_lightning_invoice(account_id, amount):
    endpoint = f"/v1/accounts/{account_id}/funds/deposits/lightning-invoices"
    body = json.dumps(
        {"asset_symbol": "BTC", "amount": amount},
        separators=(",", ":"),
    )
    nonce = time.time_ns()
    signature = get_payward_signature(endpoint, body, API_SECRET, nonce)

    headers = {
        "API-Key": API_KEY,
        "API-Nonce": str(nonce),
        "API-Sign": signature,
        "Content-Type": "application/json",
    }

    response = requests.post(
        f"{BASE_URL}{endpoint}",
        headers=headers,
        data=body,
    )
    return response.json()


lightning = create_lightning_invoice(account_id, "0.0005")
print(f"Invoice: {lightning['data']['invoice']}")
print(f"Expires at: {lightning['data'].get('expires_at')}")

async function createLightningInvoice(accountId, amount) {
  const endpoint = `/v1/accounts/${accountId}/funds/deposits/lightning-invoices`;
  const body = JSON.stringify({ asset_symbol: 'BTC', amount });
  const nonce = process.hrtime.bigint().toString();
  const signature = getPaywardSignature(endpoint, body, API_SECRET, nonce);

  const response = await fetch(`${BASE_URL}${endpoint}`, {
    method: 'POST',
    headers: {
      'API-Key': API_KEY,
      'API-Nonce': nonce,
      'API-Sign': signature,
      'Content-Type': 'application/json',
    },
    body,
  });

  return response.json();
}

const lightning = await createLightningInvoice(accountId, '0.0005');
console.log('Invoice:', lightning.data.invoice);
console.log('Expires at:', lightning.data.expires_at);

{
  "data": {
    "invoice": "lnbc500u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sqdqqcqzpgxqyz5vqsp5usyc4lk9chsfp53kvcnvq456ganh60d89reykdngsmtj6yw3nhvq9qyyssqjcewm5cjwz4a6rfjx77c490yced6pemk0upkxhy89cmm7sct66k8gneanwykzgdrwrfje69h9u5u0w57rrcsysas7gadwmzxc8c6t0spjazup6",
    "expires_at": "2026-08-03T12:34:56Z"
  }
}

A Lightning invoice is single-use, must be paid in full, and cannot be paid after expires_at. Invoice creation is not idempotent. If a request has an unknown outcome, create a new invoice; unpaid invoices expire on their own.

Reusable-address UI flow

Best practices

Always display tag/memo: For networks that require a tag or memo (XRP, XLM, etc.), prominently display it alongside the address. Missing tags/memos can result in lost funds.
Set expectations: Show minimum amounts and est_confirmation_time from the methods response so users know what to expect before sending funds.
Use fresh responses: Available methods, addresses and limits are user-specific and may change based on account standing, remaining limits, or regional regulations. Fetch fresh data before displaying options rather than relying on cached results.

Deposit webhook events

Event	Meaning
`funds.deposit_received`	The deposit was received and awaits confirmations/checks
`funds.deposit_held`	The deposit is held pending review or additional checks
`funds.deposit_credited`	The deposit was credited and can now be used
`funds.deposit_returned`	The deposit was returned to its source
`funds.deposit_failed`	The deposit failed and will not be credited

All deposit lifecycle events contain type, transaction_id, user_id, and account_id. They can also contain amount and fee:

{
  "amount": {
    "asset": "USD",
    "value": "100.00"
  },
  "fee": {
    "asset": "USD",
    "value": "0"
  }
}

amount is the total deposit amount, inclusive of the fee. PWS includes it when both the source value and its asset can be resolved. fee is optional. PWS includes it only when the source provides both the fee value and its asset and the asset can be resolved. This includes an explicitly provided zero fee. If the fee or its asset is unavailable, PWS omits fee rather than assuming that it is zero or that it uses the deposit amount’s asset. The availability of amount and fee is independent of the lifecycle event type. Treat absent fields as unavailable; PWS does not return them as null. Returned and failed deposits also contain a required reason field. PWS normalizes it to one of account_details_mismatch, limit_exceeded, duplicate, account_restricted, or other. Other deposit lifecycle events do not contain reason. A deposit can produce multiple lifecycle events as it progresses. Treat each webhook as a notification and use the Portfolio Transactions endpoint for reconciliation. Deliveries can be repeated, so use the svix-id header as the deduplication key and return a 2xx response after accepting the event. These events describe the lifecycle of a deposit. They are distinct from conversion.deposit_* events, which describe the inbound funding leg of a conversion.

Crypto withdrawals

Create a normal crypto withdrawal to a saved funding address. Funding calculates the fee and validates the method, network, destination, limits, activation, account state, and Travel Rule requirements. Quote the fee first when you need to show it to a user before they commit.

Withdrawal workflow

List withdrawal methods

Choose a method or network and inspect its required address_fields.GET /v1/accounts/{account_id}/funds/withdrawals/methods/{asset_symbol}

Check withdrawal limits

Retrieve the current maximum and rolling limits for each available method.GET /v1/accounts/{account_id}/funds/withdrawals/limits/{asset_symbol}

Select a funding address

List and reuse a compatible address_id. Register a destination first when no suitable address exists.GET /v1/accounts/{account_id}/funds/addressesPOST /v1/accounts/{account_id}/funds/addresses

Quote the withdrawal fee before you display it

Get the fee for a gross amount, plus the short-lived fee_token you carry into the next step.POST /v1/accounts/{account_id}/funds/fees

Create the withdrawal

Submit the selected scope, saved address_id, public asset symbol, and gross amount.POST /v1/accounts/{account_id}/funds/withdrawals

Handle address-ownership verification

If the request returns withdrawal_verification_required, complete a supported Travel Rule verification method.

Reconcile through Portfolio

Use the returned withdrawal_id as reference.id with reference.kind=funding.

To safely retry a withdrawal after a timeout or another unknown outcome, generate a UUIDv4 Idempotency-Key and reuse the same key for each retry. The header is optional. If you omit it, each request is treated as a new withdrawal request. Exact Portfolio reconciliation requires the withdrawal_id returned by a successful create response.

Step 1: list withdrawal methods

Use each method’s id as scope.method_id, or its network_id as scope.network_id. Network scope succeeds only when Funding can resolve exactly one eligible method for the requested asset. Otherwise, retry with a specific method ID. fee and minimum are informational and can change before submission. To get fee terms for a specific amount that you can carry into withdrawal creation, quote them in Step 4.

{
  "data": [
    {
      "id": "2fa11f79-eeba-4d4e-afda-029abff6e29e",
      "network_id": "6d7f9c7e-588d-4e56-a6f7-f1e9ada7e639",
      "network": "Bitcoin",
      "fee": {
        "symbol": "BTC",
        "name": "Bitcoin",
        "type": "crypto",
        "amount": "0.00005000"
      },
      "minimum": {
        "symbol": "BTC",
        "name": "Bitcoin",
        "type": "crypto",
        "amount": "0.00050000"
      },
      "address_fields": [
        {
          "key": "address",
          "required": true
        }
      ]
    }
  ]
}

Step 2: check withdrawal limits

Retrieve the account-specific limits for the asset after choosing a method. Use only entries whose method_id appears in the withdrawal-methods response for the same account and asset. Compare your intended amount against maximum_amount, and check period_limits too: count-based limits do not reduce maximum_amount, so a withdrawal can still be rejected when maximum_amount looks sufficient. All values are point-in-time and can change before submission. See List withdrawal limits for the full field reference.

{
  "data": [
    {
      "method_id": "2fa11f79-eeba-4d4e-afda-029abff6e29e",
      "maximum_amount": {
        "symbol": "BTC",
        "name": "Bitcoin",
        "type": "crypto",
        "amount": "0.75"
      },
      "maximum_reason": "limits",
      "period_limits": [
        {
          "type": "withdrawal_attempts",
          "period": "daily",
          "period_seconds": 86400,
          "remaining": "3",
          "maximum": "10"
        }
      ]
    }
  ]
}

Step 3: select or create a funding address

List the account’s funding addresses and reuse a compatible destination. Register a new address only when no suitable address exists.

Funding-address creation is not idempotent. If the request has an unknown outcome, list the account’s funding addresses before creating another one. Do not automatically retry.

List existing funding addresses

The first request can include page_size. To continue, send the returned page_token and the same method_id when filtering. Omit page_size; the token preserves it. The token is bound to the selected account and method filter. Pass method_id to filter by that method’s scope; omitting it returns every funding address on the account. Because scopes nest (method → network → network group), a matching address may be registered more broadly and report a network_id or network_group_id in scope instead of the method_id you filtered on. An empty method_id is rejected as a validation error, not treated as no filter.

def list_funding_addresses(account_id, method_id=None, page_size=20, page_token=None):
    endpoint = f"/v1/accounts/{account_id}/funds/addresses"
    params = {"page_token": page_token} if page_token else {"page_size": page_size}
    if method_id is not None:
        params["method_id"] = method_id
    nonce = time.time_ns()
    signature = get_payward_signature(endpoint, None, API_SECRET, nonce, params)

    headers = {
        "API-Key": API_KEY,
        "API-Nonce": str(nonce),
        "API-Sign": signature,
    }
    response = requests.get(
        f"{BASE_URL}{endpoint}",
        headers=headers,
        params=params,
    )
    return response.json()

async function listFundingAddresses(accountId, methodId = null, pageSize = 20, pageToken = null) {
  const endpoint = `/v1/accounts/${accountId}/funds/addresses`;
  const params = pageToken ? { page_token: pageToken } : { page_size: pageSize };
  if (methodId !== null) params.method_id = methodId;
  const nonce = process.hrtime.bigint().toString();
  const signature = getPaywardSignature(endpoint, null, API_SECRET, nonce, params);
  const query = new URLSearchParams(params);

  const response = await fetch(`${BASE_URL}${endpoint}?${query}`, {
    headers: {
      'API-Key': API_KEY,
      'API-Nonce': nonce,
      'API-Sign': signature,
    },
  });
  return response.json();
}

{
  "data": [
    {
      "address_id": "AB12345-6789A-BCDEFG",
      "scope": {
        "method_id": "2fa11f79-eeba-4d4e-afda-029abff6e29e"
      },
      "name": "Primary BTC wallet",
      "address_details": {
        "crypto": {
          "address": "bc1qexampleaddress",
          "tag": "123",
          "memo": "456"
        }
      }
    }
  ],
  "next_page_token": "MjoyRHuBXSgoe0mDHt-iFALROW46EGdvk_trgja31Vwr7H4"
}

Create a funding address

Set exactly one scope:

Use method_id when the destination should be registered for one withdrawal method.
Use network_id when the destination should be valid for methods on that network.

Funding validates the scope and address fields. Collect the fields identified by address_fields in the withdrawal-method response. Do not add local address-validation rules.

import json


def create_funding_address(account_id, scope, name, address, tag=None, memo=None):
    endpoint = f"/v1/accounts/{account_id}/funds/addresses"
    crypto = {"address": address}
    if tag:
        crypto["tag"] = tag
    if memo:
        crypto["memo"] = memo

    body = json.dumps(
        {
            "scope": scope,
            "name": name,
            "address_details": {"crypto": crypto},
        },
        separators=(",", ":"),
    )
    nonce = time.time_ns()
    signature = get_payward_signature(endpoint, body, API_SECRET, nonce)

    headers = {
        "API-Key": API_KEY,
        "API-Nonce": str(nonce),
        "API-Sign": signature,
        "Content-Type": "application/json",
    }
    response = requests.post(
        f"{BASE_URL}{endpoint}",
        headers=headers,
        data=body,
    )
    return response.json()

async function createFundingAddress(accountId, scope, name, address, tag = null, memo = null) {
  const endpoint = `/v1/accounts/${accountId}/funds/addresses`;
  const crypto = { address };
  if (tag) crypto.tag = tag;
  if (memo) crypto.memo = memo;

  const body = JSON.stringify({
    scope,
    name,
    address_details: { crypto },
  });
  const nonce = process.hrtime.bigint().toString();
  const signature = getPaywardSignature(endpoint, body, API_SECRET, nonce);

  const response = await fetch(`${BASE_URL}${endpoint}`, {
    method: 'POST',
    headers: {
      'API-Key': API_KEY,
      'API-Nonce': nonce,
      'API-Sign': signature,
      'Content-Type': 'application/json',
    },
    body,
  });
  return response.json();
}

Successful creation returns 200:

{
  "data": {
    "address_id": "AB12345-6789A-BCDEFG"
  }
}

The name must be unique per account and is limited to 64 characters. A create request can return these 409 codes:

Code	Meaning
`withdrawal_address_limit_reached`	The account reached the address limit for the selected scope.
`withdrawal_address_already_exists`	A matching address or name already exists for the selected scope.
`withdrawal_address_account_settings_locked`	Global Settings Lock temporarily prevents address changes.

Address limits vary by account and scope and are not exposed by this API. Reuse an existing address or contact support when the limit is reached.

Get, rename, or delete a funding address

Use the stable address_id in the member path:

GET /v1/accounts/{account_id}/funds/addresses/{address_id} returns the saved scope, name, and address details.
PATCH /v1/accounts/{account_id}/funds/addresses/{address_id} renames the address and returns 204.
DELETE /v1/accounts/{account_id}/funds/addresses/{address_id} deletes the address and returns 204.

Get and delete return 404 when the address is absent or unavailable to the selected account. Update can return 403 when the caller is not allowed to change the address. Always enforce account-to-address ownership in your integration.

Step 4: quote the withdrawal fee before you display it

Quote the fee for the gross amount you intend to withdraw. Use a method id from Step 1 as method_id. Fiat methods succeed but omit fee_token, since their fees don’t change between quote and withdrawal. Skip this step when you do not need to show a fee before submitting. amount is the gross amount, inclusive of the fee.

import json


def calculate_funding_fees(account_id, method_id, amount):
    endpoint = f"/v1/accounts/{account_id}/funds/fees"
    body = json.dumps(
        {
            "method_id": method_id,
            "amount": amount,
        },
        separators=(",", ":"),
    )
    nonce = time.time_ns()
    signature = get_payward_signature(endpoint, body, API_SECRET, nonce)

    headers = {
        "API-Key": API_KEY,
        "API-Nonce": str(nonce),
        "API-Sign": signature,
        "Content-Type": "application/json",
    }
    response = requests.post(
        f"{BASE_URL}{endpoint}",
        headers=headers,
        data=body,
    )
    return response.json()


quote = calculate_funding_fees(
    account_id,
    "2fa11f79-eeba-4d4e-afda-029abff6e29e",
    "0.01000000",
)

async function calculateFundingFees(accountId, methodId, amount) {
  const endpoint = `/v1/accounts/${accountId}/funds/fees`;
  const body = JSON.stringify({
    method_id: methodId,
    amount,
  });
  const nonce = process.hrtime.bigint().toString();
  const signature = getPaywardSignature(endpoint, body, API_SECRET, nonce);

  const response = await fetch(`${BASE_URL}${endpoint}`, {
    method: 'POST',
    headers: {
      'API-Key': API_KEY,
      'API-Nonce': nonce,
      'API-Sign': signature,
      'Content-Type': 'application/json',
    },
    body,
  });
  return response.json();
}

const quote = await calculateFundingFees(accountId, '2fa11f79-eeba-4d4e-afda-029abff6e29e', '0.01000000');

A successful quote returns 201:

{
  "data": {
    "fee": {
      "symbol": "BTC",
      "name": "Bitcoin",
      "type": "crypto",
      "amount": "0.00005000"
    },
    "gross_amount": {
      "symbol": "BTC",
      "name": "Bitcoin",
      "type": "crypto",
      "amount": "0.01000000"
    },
    "net_amount": {
      "symbol": "BTC",
      "name": "Bitcoin",
      "type": "crypto",
      "amount": "0.00995000"
    },
    "fee_token": "eyJ3aXRoZHJhd2FsX2ZlZSI6Ii4uLiJ9"
  }
}

net_amount is what reaches the destination, and for same-asset crypto fees net_amount + fee equals gross_amount. Each request returns a new quote and moves no funds. Pass fee_token to Step 5 to reuse this quote’s fee terms. Treat the token as opaque and sensitive: do not parse or modify it, do not log it, and do not reuse it across users or accounts. The quote checks the method and the amount only. Funding still checks balance, method minimums, address compatibility, and Travel Rule requirements when you create the withdrawal.

Step 5: create the withdrawal

amount is the gross amount debited from the account, inclusive of the fee. For same-asset crypto fees, net_amount + fee equals gross_amount. To reuse the fee terms from Step 4, send its fee_token and set scope.method_id to the id of the method you quoted. Fee tokens cannot be used with network scope. Omit fee_token to have Funding calculate the fee when the withdrawal is created. Funding recalculates the absolute fee from the token’s pinned terms and this request’s amount. Submit the same amount as the quote to reproduce the fee you displayed.

The token does not pin the amount. Submitting a different amount does not invalidate the token, but Funding then recalculates the fee for the amount you submit, so the fee charged differs from the fee you displayed. The request is still subject to the usual amount checks. Request a new quote whenever the amount changes.

A 400 on fee_token means no withdrawal was created. Request a new quote and resubmit with its token. Do not resend a rejected token.

import json


def create_withdrawal(account_id, scope, address_id, symbol, amount, fee_token=None, idempotency_key=None):
    endpoint = f"/v1/accounts/{account_id}/funds/withdrawals"
    payload = {
        "scope": scope,
        "address_id": address_id,
        "symbol": symbol,
        "amount": amount,
    }
    if fee_token is not None:
        payload["fee_token"] = fee_token
    body = json.dumps(payload, separators=(",", ":"))
    nonce = time.time_ns()
    signature = get_payward_signature(endpoint, body, API_SECRET, nonce)

    headers = {
        "API-Key": API_KEY,
        "API-Nonce": str(nonce),
        "API-Sign": signature,
        "Content-Type": "application/json",
    }
    if idempotency_key is not None:
        headers["Idempotency-Key"] = idempotency_key
    response = requests.post(
        f"{BASE_URL}{endpoint}",
        headers=headers,
        data=body,
    )
    return response.json()


create_withdrawal(
    account_id,
    {"method_id": "2fa11f79-eeba-4d4e-afda-029abff6e29e"},
    "AB12345-6789A-BCDEFG",
    "BTC",
    "0.01000000",
    fee_token=quote["data"]["fee_token"],
    idempotency_key="550e8400-e29b-41d4-a716-446655440000",
)

async function createWithdrawal(accountId, scope, addressId, symbol, amount, feeToken, idempotencyKey) {
  const endpoint = `/v1/accounts/${accountId}/funds/withdrawals`;
  const body = JSON.stringify({
    scope,
    address_id: addressId,
    symbol,
    amount,
    ...(feeToken ? { fee_token: feeToken } : {}),
  });
  const nonce = process.hrtime.bigint().toString();
  const signature = getPaywardSignature(endpoint, body, API_SECRET, nonce);

  const response = await fetch(`${BASE_URL}${endpoint}`, {
    method: 'POST',
    headers: {
      'API-Key': API_KEY,
      'API-Nonce': nonce,
      'API-Sign': signature,
      'Content-Type': 'application/json',
      ...(idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {}),
    },
    body,
  });
  return response.json();
}

await createWithdrawal(
  accountId,
  { method_id: '2fa11f79-eeba-4d4e-afda-029abff6e29e' },
  'AB12345-6789A-BCDEFG',
  'BTC',
  '0.01000000',
  quote.data.fee_token,
  '550e8400-e29b-41d4-a716-446655440000',
);

Successful withdrawal creation returns 201:

{
  "data": {
    "withdrawal_id": "FTSBuuG-9BctU4m3Emt88submmZVKY",
    "net_amount": {
      "symbol": "BTC",
      "name": "Bitcoin",
      "type": "crypto",
      "amount": "0.00995000"
    },
    "gross_amount": {
      "symbol": "BTC",
      "name": "Bitcoin",
      "type": "crypto",
      "amount": "0.01000000"
    },
    "fee": {
      "symbol": "BTC",
      "name": "Bitcoin",
      "type": "crypto",
      "amount": "0.00005000"
    }
  }
}

Address-ownership verification

When the response is 409 withdrawal_verification_required, read verification_methods. Funding can return self_attestation, satoshi_test, or digital_signature. The PWS Travel Rule verification endpoint currently accepts self_attestation from this list. Complete it through POST /v1/users/{user_id}/travel-rule/verifications, then submit a new withdrawal request. Contact support when the response does not include a method that the endpoint supports.

Reconcile the withdrawal

List GET /v1/accounts/{account_id}/portfolio/transactions?types=withdrawal. Match the transaction whose reference.kind is funding and whose reference.id equals the returned withdrawal_id. Portfolio is the canonical status and history surface. Do not wait for a withdrawal lifecycle webhook; this API does not publish one.

Withdrawal best practices

Reuse saved addresses: List funding addresses before creating another destination.
Use the exact scope: Prefer method_id when multiple methods exist on the same network.
Quote the fee before you display it: Method-list fees are estimates. Quote the fee for the amount you intend to withdraw, then send that quote’s fee_token with the same amount.
Reuse idempotency keys for retries: Generate a UUIDv4 key before creating a withdrawal. Reuse it after an unknown outcome. If you omit the header, reconcile through Portfolio before submitting another withdrawal.
Protect routing fields: Preserve required tags and memos, and do not log complete destination details.

Common errors

HTTP status	Cause	Remediation
`400 Bad Request`	Invalid scope, address, symbol, amount, insufficient balance, or method limits	Correct the named field in `error.causes`; use a method ID when network scope is ambiguous
`400 Bad Request`	Invalid or expired `fee_token`, or a fee token sent with `network_id` scope	Request a new quote; send its token with `scope.method_id`
`400 Bad Request`	`method_id` is unknown or does not support fee quotes	Quote with a method `id` from Step 1
`401 Unauthorized`	Missing or invalid API credentials	Verify `API-Key`, `API-Nonce`, and `API-Sign`
`403 Forbidden`	The caller is not allowed, or the funding method requires activation or unsupported step-up	Confirm permissions and select an available method
`409 Conflict`	Address ownership verification or Global Settings Lock blocks the withdrawal	Complete self-attestation when returned; otherwise contact support, or wait for the lock
`429 Too Many Requests`	Rate limit exceeded	Back off and retry according to the rate-limit headers
`500 Internal`	Unexpected or malformed upstream response	Contact support; do not retry automatically
`503 Unavailable`	A required service is temporarily unavailable	Treat the outcome as unknown and contact support
`504 Deadline Exceeded`	The request deadline elapsed	Treat the outcome as unknown and contact support

API reference

Endpoint	Method	API reference
`/v1/accounts/{account_id}/funds/deposits/methods/{asset_symbol}`	GET	List deposit methods
`/v1/accounts/{account_id}/funds/deposits/methods/{method_id}/activation`	POST	Activate deposit method
`/v1/accounts/{account_id}/funds/deposits/addresses`	GET	List deposit addresses
`/v1/accounts/{account_id}/funds/deposits/addresses`	POST	Claim deposit address
`/v1/accounts/{account_id}/funds/deposits/lightning-invoices`	POST	Create Lightning invoice
`/v1/accounts/{account_id}/funds/withdrawals/methods/{asset_symbol}`	GET	List withdrawal methods
`/v1/accounts/{account_id}/funds/withdrawals/limits/{asset_symbol}`	GET	List withdrawal limits
`/v1/accounts/{account_id}/funds/addresses`	GET	List funding addresses
`/v1/accounts/{account_id}/funds/addresses`	POST	Create funding address
`/v1/accounts/{account_id}/funds/addresses/{address_id}`	GET	Get funding address
`/v1/accounts/{account_id}/funds/addresses/{address_id}`	PATCH	Update funding address
`/v1/accounts/{account_id}/funds/addresses/{address_id}`	DELETE	Delete funding address
`/v1/accounts/{account_id}/funds/fees`	POST	Calculate funding fees
`/v1/accounts/{account_id}/funds/withdrawals`	POST	Create withdrawal
`/v1/accounts/{account_id}/portfolio/transactions`	GET	List Portfolio transactions

Get started

Market data

Accounts

Verifications

Trade

Earn

Payments

Prerequisites

Deposits

Deposit workflow

Bank-link deposit flow

Step 1: list deposit methods

Response example

Step 2: activate a deposit method when required

Step 3: list deposit addresses

Response example

Step 4: claim a crypto deposit address

Bitcoin Lightning invoice flow

Reusable-address UI flow

Best practices

Deposit webhook events

Crypto withdrawals

Withdrawal workflow

Step 1: list withdrawal methods

Step 2: check withdrawal limits

Step 3: select or create a funding address

List existing funding addresses

Create a funding address

Get, rename, or delete a funding address

Step 4: quote the withdrawal fee before you display it

Step 5: create the withdrawal

Address-ownership verification

Reconcile the withdrawal

Withdrawal best practices

Common errors

API reference

​Prerequisites

​Deposits

​Deposit workflow

​Bank-link deposit flow

​Step 1: list deposit methods

​Response example

​Step 2: activate a deposit method when required

​Step 3: list deposit addresses

​Response example

​Step 4: claim a crypto deposit address

​Bitcoin Lightning invoice flow

​Reusable-address UI flow

​Best practices

​Deposit webhook events

​Crypto withdrawals

​Withdrawal workflow

​Step 1: list withdrawal methods

​Step 2: check withdrawal limits

​Step 3: select or create a funding address

​List existing funding addresses

​Create a funding address

​Get, rename, or delete a funding address

​Step 4: quote the withdrawal fee before you display it

​Step 5: create the withdrawal

​Address-ownership verification

​Reconcile the withdrawal

​Withdrawal best practices

​Common errors

​API reference

Prerequisites

Deposits

Deposit workflow

Bank-link deposit flow

Step 1: list deposit methods

Response example

Step 2: activate a deposit method when required

Step 3: list deposit addresses

Response example

Step 4: claim a crypto deposit address

Bitcoin Lightning invoice flow

Reusable-address UI flow

Best practices

Deposit webhook events

Crypto withdrawals

Withdrawal workflow

Step 1: list withdrawal methods

Step 2: check withdrawal limits

Step 3: select or create a funding address

List existing funding addresses

Create a funding address

Get, rename, or delete a funding address

Step 4: quote the withdrawal fee before you display it

Step 5: create the withdrawal

Address-ownership verification

Reconcile the withdrawal

Withdrawal best practices

Common errors

API reference