Manage Bank Instructions

Add, view, and remove your banking instructions using the below endpoints.

Create Bank Instruction

Create a new bank instruction to withdraw fiat currency.

POST https://api.aquanow.io/users/v2/addressBook

Headers

Name	Type	Required	Description
currencyType	string	Yes	Specifies the kind of payment instruction being stored. Allowed values: “fiat”
currency	String	Yes	ISO 3-letter currency code for the payment (e.g., "USD")
externalReferenceId	String	No	Optional reference ID for your bank instruction
beneficiaryType	String	Yes	"BUSINESS"
beneficiaryLegalName	String	Conditional	Required if beneficiaryType = "BUSINESS"
beneficiaryAddress	Object	Yes	Beneficiary physical address object, fields below
beneficiaryAddress.addressLine1	String	Yes	The primary street address line
beneficiaryAddress.addressLine2	String	No	Street address line 2 (e.g., suite, unit)
beneficiaryAddress.city	String	Yes	City, town, or village.
beneficiaryAddress.region	String	Yes	State/Province/Region
beneficiaryAddress.postalCode	String	Conditional	Postal code (required for countries with postal codes)
beneficiaryAddress.country	String	Yes	Two-letter ISO country code (e.g., "US")
beneficiaryAccountNumber	String	Yes	Bank account number
beneficiaryBankBic	String	Yes	SWIFT/BIC code (8-11 characters)
routingCode	String	No	Domestic routing number for the beneficiary's bank. This field is optional and will be used on a best-efforts basis to facilitate domestic payment processing when available. Please provide the following based on currency: USD: ABA routing number (9 digits) - e.g., 021000021 GBP: Sort code (6 digits, format: XX-XX-XX) - e.g., 20-00-00 CAD: routing number (9 digits. Always starts with a 0, followed by a 3 digit institution number, then a 5 digit bank transit number) - e.g., 000405002 AUD: BSB code (6 digits, format: XXX-XXX) - e.g., 062-001 JPY: Bank code (4 digits) + Branch code (3 digits) - e.g., 0001123
beneficiaryBankMemo	String	No	Wire transfer memo/reference text
beneficiaryBankAddress	Object	Yes	Bank physical address object, fields below
beneficiaryBankAddress.addressLine1	String	Yes	Bank primary street address line
beneficiaryBankAddress.addressLine2	String	No	Bank street address line 2
beneficiaryBankAddress.city	String	Yes	Bank city
beneficiaryBankAddress.region	String	Yes	Bank state/province/region
beneficiaryBankAddress.postalCode	String	Conditional	Bank postal code
beneficiaryBankAddress.country	String	Yes	Bank country (ISO 3166-1 alpha-2)
intermediaryBankName	String	No	Name of intermediary bank (if intermediary bank is required, if not, can skip intermediary fields)
intermediaryAccountNumber	String	No	Account number at intermediary bank
intermediaryBankBic	String	No	SWIFT/BIC of intermediary bank (8-11 characters)
intermediaryBankAddress	Object	No	Intermediary bank physical address
intermediaryBankAddress.addressLine1	String	No	Intermediary bank street address line 1
intermediaryBankAddress.addressLine2	String	No	Intermediary bank street address line 2
intermediaryBankAddress.city	String	No	Intermediary bank city
intermediaryBankAddress.region	String	No	Intermediary bank state/province/region
intermediaryBankAddress.postalCode	String	No	Intermediary bank postal code
intermediaryBankAddress.country	String	No	Intermediary bank country (ISO 3166-1 alpha-2)

Name	Type	Description
x-api-key*	String	{{x-api-key}} API Auth Key
x-signature*	String	Signature created using your API secret
x-nonce*	String	Timestamp in millisecond

Request Body

Response

200: OK

{
  "addressBookId": "8b6a056b-9ed9-4cc5-b8c5-eec4b9bec60a",
  "currencyType": "fiat",
  "currency": "USD",
  "externalReferenceId": "client-ref-12345",
  "status": "PENDING"
}

400: Bad Request

401: Unauthorized

404: Not found

Example Request - Individual

{
  "currency": "USD",
  "currencyType": "fiat",
  "externalReferenceId": "client-ref-12345",
  "beneficiaryType": "INDIVIDUAL",
  "beneficiaryGivenNames": "John",
  "beneficiarySurnames": "Doe",
  "beneficiaryAddress": {
    "addressLine1": "123 Main Street",
    "city": "New York",
    "region": "NY",
    "postalCode": "10001",
    "country": "US"
  },
  "beneficiaryAccountNumber": "1234567890",
  "beneficiaryBankBic": "CHASUS33",
  "beneficiaryRoutingCode": "021000021",
  "beneficiaryBankAddress": {
    "addressLine1": "456 Bank Avenue",
    "city": "New York",
    "region": "NY",
    "postalCode": "10002",
    "country": "US"
  }
}

Example Request - Business

{
  "currency": "CAD",
  "currencyType": "fiat",
  "beneficiaryType": "BUSINESS",
  "beneficiaryLegalName": "Acme Corporation Inc.",
  "beneficiaryAddress": {
    "addressLine1": "789 Corporate Boulevard",
    "city": "Toronto",
    "region": "ON",
    "postalCode": "M5H 2N2",
    "country": "CA"
  },
  "beneficiaryAccountNumber": "9876543210",
  "beneficiaryBankBic": "ROYCCAT2",
  "beneficiaryBankAddress": {
    "addressLine1": "100 King Street West",
    "city": "Toronto",
    "region": "ON",
    "postalCode": "M5X 1A1",
    "country": "CA"
  }
}

---

Get Bank Instructions

Retrieve the details of your saved bank instructions with an option to filter results. At least one query parameter must be provided.

GET https://api.aquanow.io/users/v2/addressBook

Query Parameters

Name	Type	Description
id	string	Optional. Filter by type (e.g., "fiat")
currency	String	Optional. Filter by currency (e.g., "USD")
externalReferenceId	String	Optional. Filter by client reference ID
addressBookId	String	Optional. Get specific instruction by ID

Headers

Name	Type	Description
x-api-key*	String	{{x-api-key}} API Auth Key
x-signature*	String	Signature created using your API secret
x-nonce*	String	Timestamp in millisecond

Response

200: OK

{
  "data": [
    {
      "addressBookId": "8b6a056b-9ed9-4cc5-b8c5-eec4b9bec60a",
      "currencyType": "fiat",
      "status": "ACTIVE",
      "currency": "USD",
      "externalReferenceId": "client-ref-12345",
      "beneficiaryType": "INDIVIDUAL",
      "beneficiaryGivenNames": "John",
      "beneficiarySurnames": "Doe",
      "beneficiaryAddress": {
        "addressLine1": "123 Main Street",
        "city": "New York",
        "region": "NY",
        "postalCode": "10001",
        "country": "US"
      },
      "beneficiaryAccountNumber": "1234567890",
      "beneficiaryBankBic": "CHASUS33",
      "beneficiaryRoutingCode": "021000021",
      "beneficiaryBankMemo": "memo",
      "beneficiaryBankAddress": {
        "addressLine1": "456 Bank Avenue",
        "city": "New York",
        "region": "NY",
        "postalCode": "10002",
        "country": "US"
      }
    }
  ]
}

400: Bad Request

401: Unauthorized

404: Not found

---

Delete Bank Instruction

Remove a bank instruction from your addressbook.

DELETE https://api.aquanow.io/users/v2/addressBook/{id}

Path Parameters

Name	Type	Description
id*	String	Unique identifier of the instruction to delete

Headers

Name	Type	Description
x-api-key*	String	{{x-api-key}} API Auth Key
x-signature*	String	Signature created using your API secret
x-nonce*	String	Timestamp in millisecond

Response

200: OK

{
  "addressBookId": "8b6a056b-9ed9-4cc5-b8c5-eec4b9bec60a",
  "status": "INACTIVE",
  "updatedAt": "2025-01-21T10:30:00Z"
}

400: Bad Request

401: Unauthorized

404: Not found