This section provides an OpenAPI specification covering endpoints, request/response schemas, authentication, and errors for integration and testing purposes. The specification does not represent the platform’s full feature set and will evolve over time.
openapi: 3.0.3
info:
title: Knova API
version: 0.19.0
paths:
/v1/users:
post:
tags:
- Users
summary: Register New User
description: Register new user using given user ID. Creates a new Knova wallet in the custodial wallet service.
operationId: register_user
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RegisterUserRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RegisterUserResponse'
'500':
description: |-
Possible reasons:
- failed to get user from database
- failed to create knova wallet
- failed to save user in database
/v1/users/{id}:
delete:
tags:
- Users
summary: Archive User
description: Archive an existing user.
operationId: archive_user
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EmptyResponse'
'400':
description: user cannot be archived while having asset balances
'500':
description: |-
Possible reasons:
- failed to get asset balances
- could not begin transactional query
- failed to archive user
- failed to commit database transaction
/v1/users/{id}/addresses:
get:
tags:
- Addresses
summary: List Addresses for User
description: List the blockchain addresses for a given user.
operationId: list_addresses
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
- name: page
schema:
description: Page number for paginated results
type: integer
in: query
style: form
- name: page_size
schema:
description: Page size for paginated results
type: integer
in: query
style: form
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/UserAddress'
'500':
description: failed to get address list
post:
tags:
- Addresses
summary: Generate new Address for User
description: Generate a new blockchain address for a user for a given asset code. If an address already exists for the asset code return it instead.
operationId: create_address
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAddressRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/UserAddress'
/v1/users/{id}/multiple-addresses:
post:
tags:
- Addresses
summary: Generate Multiple Addresses for User
description: Generate multiple blockchain addresses for a given user.
operationId: create_addresses
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/CreateAddressRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/UserAddress'
/v1/users/username/USERNAME:
get:
tags:
- Users
summary: Get User by Username
description: Get a user by username.
operationId: get_user_by_username
parameters:
- name: username
required: true
schema:
type: string
in: path
style: simple
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'500':
description: failed to get user from database
'404':
description: user not found
/v1/users/{id}/balances/{asset_code}:
get:
tags:
- Users
summary: Get Asset Balance from User Wallet
description: Get the balance of a user's Knova wallet for a given asset code.
operationId: get_user_balance
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
- name: asset_code
required: true
schema:
type: string
in: path
style: simple
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Balance'
'500':
description: |-
Possible reasons:
- failed to get user from database
- failed to get asset balances
'404':
description: unknown user
/v1/users/{id}/balances:
get:
tags:
- Users
summary: List all Balances from User Wallet
description: Get a list of balances for a user's Knova wallet.
operationId: list_user_balances
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
- name: asset_code
schema:
nullable: true
description: Asset code to filter results by
type: string
in: query
style: form
- name: page
schema:
description: Page number for paginated results
type: integer
in: query
style: form
- name: page_size
schema:
description: Page size for paginated results
type: integer
in: query
style: form
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Balance'
'500':
description: |-
Possible reasons:
- failed to get user from database
- failed to get asset balances
'404':
description: unknown user
/v1/users/{id}/transactions/onchain/transfer:
post:
tags:
- On-chain
summary: Initiate new On-chain Transaction
description: Initiate a new on-chain transaction to withdraw funds
operationId: initiate_onchain_txn
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/InitiateOnchainTxnRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/InitiateOnchainTxnResponse'
'400':
description: |-
Possible reasons:
- amount must be positive
- unknown asset_code
- a base asset must have a Base fee or a non_base asset must have a NonBase fee, but not any other combination
- could not parse fee_amount
- fee_amount must be greater than or equal to zero
- transaction with this external_id was already attempted
'500':
description: |-
Possible reasons:
- failed to get asset code
- failed to get authority public key
- attempt to verify existing contract failed
- failed to get treasury user
- treasury user is not configured
- failed to build request data
- failed to look up recipient user
- failed to get recipient user vault
- database error
- could not begin transactional query
- failed to save contract
- failed to save contract actions
- failed to create transaction
- failed to commit database transaction
/v1/users/{id}/transactions/internal/transfer:
post:
tags:
- Internal
summary: Initiate new Internal Transaction
operationId: initiate_internal_txn
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/InitiateInternalTxnRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/InitiateInternalTxnResponse'
'400':
description: |-
Possible reasons:
- could not parse amount: {body.amount}
- amount must be positive
- unknown asset_code
- transaction with this external_id was already attempted
'500':
description: |-
Possible reasons:
- failed to get asset code
- database error
- attempt to verify existing contract failed
- failed to get authority public key
- could not begin transactional query
- failed to save contract
- failed to save contract actions
- failed to create transaction
- failed to commit database transaction
/v1/users/{id}/transactions/onchain/mint:
post:
tags:
- On-chain
summary: Initiate new On-chain Transaction to mint assets
description: Initiate a new on-chain transaction to mint funds
operationId: mint
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MintRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/MintResponse'
'400':
description: |-
Possible reasons:
- amount must be positive
- transaction with this external_id was already attempted
- asset code not configured for vendor
- asset must not be a base asset
'500':
description: |-
Possible reasons:
- attempt to verify existing contract failed
- failed to get treasury user
- treasury user is not configured
- failed to build request data
- failed to get asset code
- failed to get authority public key
- could not begin transactional query
- failed to save contract
- failed to save contract actions
- failed to create transaction
- failed to commit database transaction
/v1/users/{id}/transactions/onchain/burn:
post:
tags:
- On-chain
summary: Initiate new On-chain Transaction to burn assets
description: Initiate a new on-chain transaction to burn funds
operationId: burn
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BurnRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BurnResponse'
'400':
description: |-
Possible reasons:
- amount must be positive
- asset code not configured for vendor
- transaction with this external_id was already attempted
- asset code not configured for vendor
- asset must not be a base asset
'500':
description: |-
Possible reasons:
- failed to get asset code
- attempt to verify existing contract failed
- failed to get treasury user
- treasury user is not configured
- failed to build request data
- failed to get asset code
- failed to get authority public key
- could not begin transactional query
- failed to save contract
- failed to save contract actions
- failed to create transaction
- failed to commit database transaction
/v1/users/{id}/transactions/onchain/trade/quote:
post:
tags:
- On-chain
summary: Get Quote for On-chain Trade Transaction
description: Get a quote for an on-chain trade transaction.
operationId: get_trade_quote
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/GetTradeQuoteRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetTradeQuoteResponse'
'400':
description: |-
Possible reasons:
- from_amount must be positive
- unknown from asset_code
- unknown to asset_code
'500':
description: |-
Possible reasons:
- failed to get vendor asset code
- failed to get vendor asset code
- failed to get quote
- failed to get quote amount
- failed to get expires_at
/v1/users/{id}/transactions/onchain/trade:
post:
tags:
- On-chain
summary: Initiate new On-chain Trade Transaction
description: Initiate a new on-chain transaction to trade assets.
operationId: initiate_trade_txn
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/InitiateTradeTxnRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/InitiateTradeTxnResponse'
'400':
description: |-
Possible reasons:
- amount must be positive
- amount must not be negative
- unknown from asset_code
- unknown to asset_code
- transaction with this external_id was already attempted
'500':
description: |-
Possible reasons:
- failed to get asset code
- failed to get asset code
- failed to get authority public key
- attempt to verify existing contract failed
- failed to get treasury user
- treasury user is not configured
- could not begin transactional query
- failed to save contract
- failed to save contract actions
- failed to create transaction
- failed to commit database transaction
/v1/users/{id}/asset-vendor-codes:
get:
tags:
- Addresses
summary: Get Asset Codes Owned by User
description: List the asset codes owned by a given user.
operationId: list_user_asset_vendor_codes
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/UserAssetVendorCode'
'500':
description: |-
Possible reasons:
- failed to get asset codes
- failed to get user address
/v1/users/{id}/transactions/{txn_id}:
get:
tags:
- Transactions
summary: Get Info on a Transaction by ID for a User
description: Get info about a transaction by ID for a given user.
operationId: get_contract_transaction
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
- name: txn_id
required: true
schema:
type: string
format: uuid
in: path
style: simple
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ContractTransaction'
/v1/users/{id}/transactions:
get:
tags:
- Transactions
summary: List Transactions by User ID
description: List the transactions for a given user.
operationId: list_contract_transactions
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
- name: page
schema:
description: Page number for paginated results
type: integer
in: query
style: form
- name: page_size
schema:
description: Page size for paginated results
type: integer
in: query
style: form
- name: asset_code
schema:
nullable: true
description: Optional asset code to filter by (e.g. BTC)
type: string
in: query
style: form
- name: contract_types
schema:
description: Contract types to filter by (defaults to all types if empty)
type: array
items:
$ref: '#/components/schemas/ContractType'
in: query
style: form
- name: status
schema:
$ref: '#/components/schemas/StatusFilter'
in: query
style: form
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ContractTransaction'
'500':
description: |-
Possible reasons:
- failed to get user from database
- failed to get transactions for user
'404':
description: unknown user
/v1/asset_restrictions/{asset_code}:
get:
tags:
- Asset Restrictions
summary: List asset restrictions for a given asset code
description: List asset restrictions for a given asset code
operationId: list_asset_restrictions
parameters:
- name: asset_code
required: true
schema:
type: string
in: path
style: simple
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListAssetRestrictionsResponse'
'500':
description: database error
/v1/asset_restrictions:
post:
tags:
- Asset Restrictions
summary: Set asset restrictions for a given asset code and role
description: Set asset restrictions for a given role
operationId: set_asset_restrictions
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SetAssetRestrictionsRequest'
required: true
responses:
'400':
description: invalid max_maker_amount format
'500':
description: |-
Possible reasons:
- database error
- database error
- database error
delete:
tags:
- Asset Restrictions
summary: Delete asset restrictions for a given asset_code and role
description: Delete asset restrictions for a given role
operationId: delete_asset_restrictions
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteAssetRestrictionsRequest'
required: true
responses:
'500':
description: |-
Possible reasons:
- database error
- database error
- database error
/v1/transactions/approval-requests:
get:
tags:
- Transactions
summary: List unapproved transactions
description: List unapproved transactions
operationId: list_approval_requests
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListApprovalRequestsResponse'
'500':
description: failed to get unapproved transaction from database
/v1/transactions/approval-requests/{uetr}:
get:
tags:
- Transactions
summary: Get an unapproved transaction by uetr
description: Get an unapproved transaction by uetr
operationId: get_approval_request
parameters:
- name: uetr
required: true
schema:
type: string
format: uuid
in: path
style: simple
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ApprovalRequest'
'500':
description: failed to get unapproved transaction from database
'404':
description: unknown approval request
/v1/transactions/approval-requests/{uetr}/approve:
post:
tags:
- Transactions
summary: Approve a transaction by uetr
description: Approve a transaction by uetr
operationId: approve_transaction
parameters:
- name: uetr
required: true
schema:
type: string
format: uuid
in: path
style: simple
responses:
'500':
description: failed to approve transaction
/v1/transactions/approval-requests/{uetr}/reject:
post:
tags:
- Transactions
summary: Reject a transaction by uetr
description: Reject a transaction by uetr
operationId: reject_transaction
parameters:
- name: uetr
required: true
schema:
type: string
format: uuid
in: path
style: simple
responses:
'500':
description: failed to reject transaction
/v1/admin/asset-codes:
get:
tags:
- Admin
summary: Get Registered Asset Code Information
description: Get information about all registered asset codes.
operationId: get_asset_codes
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AssetCode'
'400':
description: failed to get asset codes
'500':
description: failed to get vendor codes
post:
tags:
- Admin
summary: Register Asset Codes
description: Register a list of asset codes.
operationId: set_asset_codes
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AssetCode'
required: true
responses:
'400':
description: |-
Possible reasons:
- failed to set asset codes
- failed to set asset vendor code
'500':
description: |-
Possible reasons:
- failed to activate asset in omnibus vault: {vendor_code}
- failed to get authority public key
- failed to get asset authorities
- failed to add asset authority
- failed to get existing asset codes
- failed to get existing asset vendor codes
/v1/admin/asset-codes/{asset_code}:
delete:
tags:
- Admin
summary: Disable Asset Code
description: Disable an asset code.
operationId: disable_asset_code
parameters:
- name: asset_code
required: true
schema:
type: string
in: path
style: simple
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EmptyResponse'
'500':
description: failed to disable asset code
/v1/admin/asset-codes/{asset_code}/vendor/{vendor_code}:
delete:
tags:
- Admin
summary: Delete an Asset Vendor Code
description: Delete a vendor code for a given asset.
operationId: delete_asset_vendor_code
parameters:
- name: asset_code
required: true
schema:
type: string
in: path
style: simple
- name: vendor_code
required: true
schema:
$ref: '#/components/schemas/Vendor'
in: path
style: simple
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EmptyResponse'
'500':
description: failed to delete asset vendor code
/v1/admin/balances:
post:
tags:
- Admin
summary: Make an Out-of-band Update to a Wallet Balance.
description: |-
Make an out-of-band update to a wallet balance in Knova only by either issuing, redeeming, or
transferring funds from the wallet.
operationId: update_core_wallet_balance
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateDigitalTwinBalanceRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateDigitalTwinBalanceResponse'
'400':
description: |-
Possible reasons:
- unknown asset_code
- amount must be positive
- memo cannot be empty: e.g. "authorized by JG"
'500':
description: |-
Possible reasons:
- failed to get user from database
- failed to get to asset_code
- failed to get authority public key
- failed to get user from database
- could not begin transactional query
- failed to save contract
- failed to save contract actions
- failed to create transaction
- failed to commit database transaction
'404':
description: |-
Possible reasons:
- unknown user
- unknown recipient user
/v1/admin/vendors/balances/{asset_code}:
get:
tags:
- Admin
summary: Get External Vendor Balances by Asset
description: Get the balances from the various backend vendors for a given asset.
operationId: get_vendor_asset_balances
parameters:
- name: asset_code
required: true
schema:
type: string
in: path
style: simple
- name: vendors
schema:
description: Optional list of vendors to filter by
type: array
items:
$ref: '#/components/schemas/CustodyVendor'
in: query
style: form
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
additionalProperties:
type: string
format: decimal
'500':
description: |-
Possible reasons:
- failed to get vendor asset balances
- failed to get vendor asset balances
/v1/admin/vendors/all-balances:
get:
tags:
- Admin
summary: Get Vendor Asset Balances
description: Get the balance of each asset code in a vendor
operationId: get_all_vendor_asset_balances
parameters:
- name: page
schema:
description: Page number for paginated results
type: integer
in: query
style: form
- name: page_size
schema:
description: Page size for paginated results
type: integer
in: query
style: form
- name: vendors
schema:
description: Optional list of vendors to filter by
type: array
items:
$ref: '#/components/schemas/CustodyVendor'
in: query
style: form
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AllVendorAssetBalanceResponse'
'500':
description: |-
Possible reasons:
- failed to get asset codes
- failed to get vendor asset balances
/v1/admin/transactions:
get:
tags:
- Admin
summary: List All Contract Transactions
description: List all contract transactions.
operationId: list_all_contract_transactions
parameters:
- name: page
schema:
description: Page number for paginated results
type: integer
in: query
style: form
- name: page_size
schema:
description: Page size for paginated results
type: integer
in: query
style: form
- name: asset_code
schema:
nullable: true
description: Optional asset code to filter by (e.g. BTC)
type: string
in: query
style: form
- name: contract_types
schema:
description: Contract types to filter by (defaults to all types if empty)
type: array
items:
$ref: '#/components/schemas/ContractType'
in: query
style: form
- name: status
schema:
$ref: '#/components/schemas/StatusFilter'
in: query
style: form
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ContractTransaction'
'500':
description: failed to get transactions
/v1/admin/transactions/{txn_id}:
get:
tags:
- Transactions
summary: Get Info on a Transaction by ID
description: Get info about a transaction by ID.
operationId: get_contract_transaction_admin
parameters:
- name: txn_id
required: true
schema:
type: string
format: uuid
in: path
style: simple
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ContractTransaction'
/v1/admin/transactions/{txn_id}/blocks:
get:
tags:
- Transactions
summary: Get blocks for a Transaction by ID
description: Get execution blocks for a transaction by ID.
operationId: get_contract_transaction_blocks
parameters:
- name: txn_id
required: true
schema:
type: string
format: uuid
in: path
style: simple
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetContractTransactionBlocksResponse'
'500':
description: |-
Possible reasons:
- failed to get execution blocks
- failed to convert execution blocks
/v1/admin/vendors/transactions:
post:
tags:
- Admin
summary: Move Assets On-Chain to Address
description: Move assets on-chain from a given vendor to a given address.
operationId: initiate_admin_txn
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RebalanceRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RebalanceResponse'
'500':
description: |-
Possible reasons:
- failed to get vendor code from database
- unable to create transaction
'404':
description: unknown vendor code
'501':
description: invalid source vendor
/v1/admin/vendor-webhooks/resend:
post:
tags:
- Admin
summary: Resend Failed Webhooks for a Transaction
description: Resend transaction for webhook.
operationId: resend_transaction
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ResendTxnWebhooksRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionResponse'
'500':
description: failed to resend notifications
/v1/admin/vendor-webhooks/resend-failed:
post:
tags:
- Admin
summary: Resend Failed Webhooks
description: Only transactions after this datetime (unix timestamp in milliseconds) will be resent.
operationId: resend_failed
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ResendWebhooksRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/TxFailuresResponse'
'500':
description: failed to resend failed transactions
/v1/admin/users/treasury:
get:
tags:
- Admin
summary: Get Treasury User
description: |-
Get the configured treasury user. Note, the treasury user needs to be configured by calling
`POST /admin/users/treasury` endpoint as part of the initial service setup.
operationId: get_treasury_user
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'500':
description: failed to get exchange user from database
'404':
description: exchange user not configured
post:
tags:
- Admin
summary: Register Treasury User
description: |-
Register the treasury user using given optional vault ID. Creates a new Knova wallet in custodial wallet
service and sets vault in database. Note, the treasury user needs to be configured by calling
this endpoint as part of the initial service setup.
operationId: register_treasury_user
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RegisterTreasuryUserRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
description: invalid vault ID
'500':
description: |-
Possible reasons:
- failed to get exchange user from database
- failed to create knova wallet
- failed to save user in database
/v1/admin/users:
get:
tags:
- Admin
summary: List All Users with Owned Asset Codes
description: Get all users, including non-customer users, but include asset codes users own addresses in.
operationId: list_all_users
parameters:
- name: page
schema:
description: Page number for paginated results
type: integer
in: query
style: form
- name: page_size
schema:
description: Page size for paginated results
type: integer
in: query
style: form
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AllUsersAssetsResponse'
'500':
description: failed to get all users from database
/v1/admin/users/addresses:
get:
tags:
- Admin
summary: List All Addresses for User
operationId: list_all_addresses
parameters:
- name: page
schema:
description: Page number for paginated results
type: integer
in: query
style: form
- name: page_size
schema:
description: Page size for paginated results
type: integer
in: query
style: form
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/UsernameAddress'
'500':
description: |-
Possible reasons:
- failed to get all address list
- invalid vendor
/v1/admin/users/asset-balances:
get:
tags:
- Admin
summary: Get Total Asset Balances in Knova
description: Get the total balances of all assets across all users in Knova.
operationId: list_all_asset_balances
parameters:
- name: asset_code
schema:
nullable: true
description: Asset code (e.g. BTC)
type: string
in: query
style: form
- name: page
schema:
description: Page number for paginated results
type: integer
in: query
style: form
- name: page_size
schema:
description: Page size for paginated results
type: integer
in: query
style: form
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AssetTotalBalance'
'500':
description: |-
Possible reasons:
- failed to get participant asset balances
- failed to list users
- failed to list asset codes
/v1/admin/users/balances:
get:
tags:
- Admin
summary: Get Total Balances per User
description: List each user with their total balance across all assets in Knova.
operationId: list_all_user_balances
parameters:
- name: asset_code
schema:
nullable: true
description: Asset code (e.g. BTC)
type: string
in: query
style: form
- name: page
schema:
description: Page number for paginated results
type: integer
in: query
style: form
- name: page_size
schema:
description: Page size for paginated results
type: integer
in: query
style: form
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/UserAssetBalance'
'500':
description: |-
Possible reasons:
- failed to get participant asset balances
- failed to list users
- failed to parse amount
- Participant {participant} not found in customer list
/v1/admin/users/vault-balances:
get:
tags:
- Admin
summary: List Knova Vault Balances
description: Lists the balances of all vaults in Knova.
operationId: list_vault_balances
parameters:
- name: page
schema:
description: Page number for paginated results
type: integer
in: query
style: form
- name: page_size
schema:
description: Page size for paginated results
type: integer
in: query
style: form
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/UserAddressBalance'
'500':
description: |-
Possible reasons:
- failed to get participant asset balances
- failed to list all users
- failed to list asset vendor codes
- failed to get vault accounts
- failed to get vendor vaults
- asset vendor code not found
- invalid vendor code
- no vendor account found for address
- failed to parse amount
- vendor asset not found
- failed to parse custody amount
- no vendor vault found
- failed to parse amount
- vendor asset not found
- failed to parse amount
- fiat provider is not supported
/v1/admin/users/asset-vendor-codes:
post:
tags:
- Admin
summary: Get Asset Codes Owned by Given Users
operationId: list_users_asset_vendor_codes
requestBody:
content:
application/json:
schema:
type: array
items:
type: string
format: uuid
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/UserAssetVendorCode'
'500':
description: |-
Possible reasons:
- failed to get asset codes
- failed to get user address
/v1/admin/webhooks/subscriptions:
get:
tags:
- Webhooks
summary: List webhook subscriptions
description: List webhook subscriptions.
operationId: list_webhook_subscriptions
parameters:
- name: active
schema:
nullable: true
description: Optional filter for active/unactive subscriptions
type: boolean
in: query
style: form
- name: page
schema:
description: Page number for paginated results
type: integer
in: query
style: form
- name: page_size
schema:
description: Page size for paginated results
type: integer
in: query
style: form
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListWebhookSubscriptionsResponse'
'500':
description: database error
post:
tags:
- Webhooks
summary: Create a new webhook subscription
description: Create a new webhook subscription.
operationId: create_webhook_subscription
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateWebhookSubscriptionRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookSubscription'
'500':
description: |-
Possible reasons:
- database error
- database error
- database error
/v1/admin/webhooks/subscriptions/{id}:
put:
tags:
- Webhooks
summary: Update an existing webhook subscription
description: Update an existing webhook subscription.
operationId: update_webhook_subscription
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateWebhookSubscriptionRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookSubscription'
'500':
description: |-
Possible reasons:
- database error
- database error
- database error
delete:
tags:
- Webhooks
summary: Delete a webhook subscription
description: Delete a webhook subscription.
operationId: delete_webhook_subscription
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteWebhookSubscriptionRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EmptyResponse'
'500':
description: |-
Possible reasons:
- database error
- database error
- database error
/v1/admin/webhooks/deliveries:
get:
tags:
- Webhooks
summary: List Webhook History
description: List webhook history.
operationId: list_webhook_deliveries
parameters:
- name: page
schema:
description: Page number for paginated results
type: integer
in: query
style: form
- name: page_size
schema:
description: Page size for paginated results
type: integer
in: query
style: form
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListWebhookHistoryResponse'
'500':
description: database error
/v1/admin/webhooks/deliveries/{event_id}/resend:
post:
tags:
- Webhooks
summary: Resend Webhook
description: Resend a webhook by event ID.
operationId: resend_webhook
parameters:
- name: event_id
required: true
schema:
type: string
format: uuid
in: path
style: simple
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EmptyResponse'
'500':
description: |-
Possible reasons:
- database error
- database error
- database error
- database error
- database error
'404':
description: event not found
/v1/admin/usd-rates:
get:
tags:
- Admin
summary: Get USD Exchange Rates
description: Return exchange rates for supported assets relative to USD.
operationId: get_usd_rates
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/UsdRate'
/v1/network/fee-estimates:
post:
tags:
- Network
summary: Get Network Fee Estimates
description: Get estimated fees for a list of asset codes.
operationId: get_estimated_fees
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AssetCodeInput'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/EstimatedNetworkFees'
'400':
description: unknown asset code
'500':
description: |-
Possible reasons:
- failed to get asset code
- failed to get estimated fee
/v1/network/transaction-fees:
post:
tags:
- Network
summary: Get Transaction Fees
description: Get Network transaction Fees.
operationId: get_transaction_fees
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/GetTransactionFeeRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EstimatedNetworkFees'
'400':
description: unknown asset code
'500':
description: |-
Possible reasons:
- failed to get asset code
- failed to get estimated fee
/v1/admin/automation:
get:
tags:
- Automation
summary: List Automations
description: List the automations.
operationId: list_automations
parameters:
- name: page
schema:
description: Page number for paginated results
type: integer
in: query
style: form
- name: page_size
schema:
description: Page size for paginated results
type: integer
in: query
style: form
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Automation'
'500':
description: |-
Possible reasons:
- failed to get automations from database
- failed to convert automations
post:
tags:
- Automation
summary: Create New Automation
description: Create a new automation.
operationId: set_automation
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SetAutomationRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SetAutomationResponse'
'400':
description: "Possible reasons:\n- \n- failed to serialize trigger\n- failed to serialize condition\n- failed to serialize action\n- failed to derive next date from cron schedule\n- failed to store automation"
'500':
description: |-
Possible reasons:
- failed to begin transaction
- failed to write commit
/v1/admin/automation/{id}:
get:
tags:
- Automation
summary: Get Automation
description: Get an automation by ID.
operationId: get_automation
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Automation'
'500':
description: |-
Possible reasons:
- failed to get automation from database
- failed to deserialize automation
'404':
description: unknown automation
post:
tags:
- Automation
summary: Update Automation
operationId: update_automation
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SetAutomationRequest'
required: true
responses:
'400':
description: "Possible reasons:\n- \n- failed to serialize trigger\n- failed to serialize condition\n- failed to serialize action\n- failed to derive next date from cron schedule\n- failed to update automation"
'500':
description: |-
Possible reasons:
- failed to begin transaction
- failed to write commit
delete:
tags:
- Automation
summary: Delete Automation by ID
description: Delete an automation by ID.
operationId: delete_automation
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
responses:
'400':
description: failed to delete automation
'500':
description: |-
Possible reasons:
- failed to begin transaction
- failed to write commit
/v1/admin/automation/capabilities:
get:
tags:
- Automation
summary: Get Automation Capabilities
description: |-
Get the automation capabilities as a list of valid combinations of triggers, conditions, and
actions
operationId: get_automation_capabilities
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetAutomationCapabilitiesResponse'
'500':
description: failed to get capabilities
/v1/users/{id}/automation:
get:
tags:
- Automation
summary: List User Automations
description: List the automations associated with a user.
operationId: list_user_automations
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
- name: page
schema:
description: Page number for paginated results
type: integer
in: query
style: form
- name: page_size
schema:
description: Page size for paginated results
type: integer
in: query
style: form
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Automation'
'500':
description: |-
Possible reasons:
- failed to get automations from database
- failed to convert automations
/v1/admin/automation/{id}/runs:
get:
tags:
- Automation
summary: List Automation Runs
description: List the runs for an automation.
operationId: list_automation_runs
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
- name: page
schema:
description: Page number for paginated results
type: integer
in: query
style: form
- name: page_size
schema:
description: Page size for paginated results
type: integer
in: query
style: form
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AutomationRun'
'500':
description: failed to get automation runs from database
/v1/admin/automation/{id}/status:
post:
tags:
- Automation
summary: Enable/Disable Automation
description: Enable/Disable an automation by ID.
operationId: set_automation_status
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SetAutomationStatusRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SetAutomationStatusResponse'
'500':
description: |-
Possible reasons:
- failed to begin database transaction
- failed to set automation status
- failed to write commit
/v1/users/{id}/transactions/internal/trade/{trade_id}:
get:
tags:
- Internal
summary: Get Info on Trade Transaction
description: Get info about a trade transaction by transaction ID.
operationId: get_trade_transaction
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
- name: trade_id
required: true
schema:
type: string
format: uuid
in: path
style: simple
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Trade'
'500':
description: |-
Possible reasons:
- failed to get user from database
- failed to get trade from database
- failed to get trade fills from database
- failed to get trade fundings from database
'404':
description: |-
Possible reasons:
- unknown user
- unknown trade
/v1/users/{id}/transactions/internal/trade:
get:
tags:
- Internal
summary: List Info on Trade Transactions by User
description: Get list of trade transactions by user.
operationId: list_trade_transactions
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
- name: page
schema:
description: Page number for paginated results
type: integer
in: query
style: form
- name: page_size
schema:
description: Page size for paginated results
type: integer
in: query
style: form
- name: from_asset_code
schema:
nullable: true
description: Filter by asset code held by user before trade (e.g. BTC)
type: string
in: query
style: form
- name: to_asset_code
schema:
nullable: true
description: Filter by asset code held by user after trade (e.g. BTC)
type: string
in: query
style: form
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Trade'
'500':
description: |-
Possible reasons:
- failed to get user from database
- failed to get trades and fills from database
- failed to get trade refunds from database
'404':
description: unknown user
post:
tags:
- Internal
summary: Initiate new Trade Transaction
description: Initiate a new trade transaction in Knova and lock assets for trade.
operationId: initiate_trade_transaction
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/InitiateTradeRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/InitiateTradeResponse'
'400':
description: |-
Possible reasons:
- trade with this external_id already attempted
- unknown asset_code
- unknown asset_code
'500':
description: "Possible reasons:\n- attempt to verify existing trade request failed\n- failed to get from asset_code\n- failed to get to asset_code\n- could not begin transactional query\n- failed to save trade request\n- failed to save trade funding request\n- \n- failed to create transaction\n- failed to commit database transaction"
/v1/users/{id}/transactions/internal/trade/{trade_id}/fill:
post:
tags:
- Internal
summary: Fill Trade Order
description: Fill a trade order.
operationId: fill_trade_transaction
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
- name: trade_id
required: true
schema:
type: string
format: uuid
in: path
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SingleTradeFillRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SingleTradeFillResponse'
'400':
description: |-
Possible reasons:
- trades not allowed for internal users
- initiate trade is missing
- trade already in terminal state
'500':
description: |-
Possible reasons:
- failed to get user from database
- failed to get market_maker from database
- attempt to verify existing trade request failed
- could not begin transactional query
- failed to fill trade
- failed to commit database transaction
- could not begin transactional query
- could not close trade
- failed to commit database transaction
'404':
description: |-
Possible reasons:
- unknown user
- unknown market maker
/v1/users/{id}/transactions/internal/trade/{trade_id}/close:
post:
tags:
- Internal
summary: Close Trade
description: Close trade and send any remaining locked funds back to the user.
operationId: close_trade_transaction
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
- name: trade_id
required: true
schema:
type: string
format: uuid
in: path
style: simple
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CloseTradeResponse'
'500':
description: |-
Possible reasons:
- failed to get user from database
- could not begin transactional query
- failed to close trade
- failed to commit database transaction
'404':
description: unknown user
/v1/market-makers:
get:
tags:
- Market Makers
summary: Get List of Market Makers
description: Get list of the registered Market Makers.
operationId: list_market_makers
parameters:
- name: page
schema:
description: Page number for paginated results
type: integer
in: query
style: form
- name: page_size
schema:
description: Page size for paginated results
type: integer
in: query
style: form
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/MarketMaker'
'400':
description: failed to get market makers
post:
tags:
- Market Makers
summary: Register New Market Maker
description: Register a new Market Maker. Creates a new Knova wallet in the custodial wallet service.
operationId: set_market_maker
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateMarketMakerRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/MarketMaker'
'500':
description: |-
Possible reasons:
- failed to create knova wallet
- failed to save market maker in database
/v1/market-makers/{id}:
get:
tags:
- Market Makers
summary: Get Details of Market Maker
description: Retrieve detailed information about a specific Market Maker by its ID.
operationId: get_market_maker
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/MarketMaker'
'500':
description: failed to get user from database
'404':
description: unknown market maker
/v1/market-makers/{id}/fund:
post:
tags:
- Market Makers
summary: Increase Market Maker Balance by Asset
description: Increase the wallet balance of a Market Maker for a particular asset code.
operationId: fund_market_maker
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FundMarketMakerRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EmptyResponse'
'500':
description: |-
Possible reasons:
- failed to get user from database
- failed to get asset_code
- failed to get authority public key
- failed to create transaction
'404':
description: |-
Possible reasons:
- unknown market maker
- unknown asset_code
/v1/market-makers/{id}/balances/{asset_code}:
get:
tags:
- Market Makers
summary: Get Market Maker Balance by Asset
description: Get the balance of a Market Maker's Knova wallet for a given asset code.
operationId: get_market_maker_balance
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
- name: asset_code
required: true
schema:
type: string
in: path
style: simple
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Balance'
'500':
description: |-
Possible reasons:
- failed to get market maker from database
- failed to get asset balances
'404':
description: unknown market maker
/v1/market-makers/{id}/balances:
get:
tags:
- Market Makers
summary: Get Market Maker Balances
description: Get a list of balances for a Market Maker's Knova wallet.
operationId: list_market_maker_balances
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
- name: asset_code
schema:
nullable: true
description: Asset code to filter results by
type: string
in: query
style: form
- name: page
schema:
description: Page number for paginated results
type: integer
in: query
style: form
- name: page_size
schema:
description: Page size for paginated results
type: integer
in: query
style: form
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Balance'
'500':
description: |-
Possible reasons:
- failed to get market maker from database
- failed to get asset balances
'404':
description: unknown market maker
/v1/admin/trades/retry-fill:
post:
tags:
- Admin
summary: Retry Failed Trade Fill Transaction
description: Retry the Knova transaction for a trade fill with `Failed` status.
operationId: admin_retry_failed_trade_fill
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RetryFailedTradeFillRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RetryFailedTradeFillResponse'
'400':
description: |-
Possible reasons:
- cannot retry fill in Completed state
- unknown from asset_code
- unknown to asset_code
- unknown fee asset_code
'500':
description: |-
Possible reasons:
- failed to get trade fill from database
- failed to get trade from database
- failed to get user from database
- failed to get market maker from database
- failed to query exchange user
- failed to get treasury public key
- failed to get from asset_code
- failed to get to asset_code
- failed to get fee asset_code
- could not begin transactional query
- failed to save update fill trade
- failed to save fill trade request
- failed to create transaction
- failed to commit database transaction
'404':
description: |-
Possible reasons:
- unknown trade fill
- unknown trade
- unknown user
- unknown market maker
/v1/admin/trades/retry-refund:
post:
tags:
- Admin
summary: Retry Failed Refund Transaction
description: Retry the Knova transaction for a trade funding (`Refund` only) with `Failed` status.
operationId: admin_retry_failed_trade_refund
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RetryFailedTradeRefundRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RetryFailedTradeRefundResponse'
'400':
description: |-
Possible reasons:
- cannot retry funding in Completed state
- unknown from asset_code
'500':
description: |-
Possible reasons:
- failed to get trade funding from database
- failed to get trade from database
- failed to get user from database
- failed to get from asset_code
- failed to get treasury public key: {err}
- could not begin transactional query
- failed to save update funding trade
- failed to save funding trade request
- failed to create transaction
- failed to commit database transaction
'404':
description: |-
Possible reasons:
- unknown trade or no refund found
- unknown trade
- unknown user
/v1/admin/users/transactions/trades:
get:
tags:
- Admin
summary: List All Trade Transactions
description: Retrieve a list of all trade transactions.
operationId: list_all_trade_transactions
parameters:
- name: last_hours
schema:
nullable: true
description: Limit results to last N hours (e.g. last 24 hours)
type: integer
in: query
style: form
- name: page
schema:
description: Page number for paginated results
type: integer
in: query
style: form
- name: page_size
schema:
description: Page size for paginated results
type: integer
in: query
style: form
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Trade'
'500':
description: |-
Possible reasons:
- failed to get trades and fills from database
- failed to get trade refunds from database
/v1/users/{id}/transactions/fiat/transfer:
post:
tags:
- Fiat
summary: Initiate new Fiat Transaction
operationId: initiate_fiat_provider_txn
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FiatTxnRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/FiatTxnResponse'
'400':
description: |-
Possible reasons:
- amount must be positive
- transaction with this external_id was already attempted
'500':
description: |-
Possible reasons:
- database error
- attempt to verify existing contract failed
- database error
- database error
- database error
- could not begin transactional query
- failed to save contract
- failed to create transaction
- failed to commit database transaction
'404':
description: "Possible reasons:\n- \n- fiat provider config not found for `user_id`\n- fiat provider config not found for `to`\n- fiat provider config not found\n- failed to get authority public key"
/v1/users/{id}/account:
get:
tags:
- Fiat
summary: List Fiat Provider config for a given user
description: Get Fiat Provider for a given user
operationId: get_fiat_provider_config
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/FiatProvider'
'500':
description: database error
'404':
description: ''
post:
tags:
- Fiat
summary: Set Fiat Provider Configuration
description: Set Fiat Provider configuration for the service.
operationId: set_fiat_provider_config
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SetFiatProviderRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SetFiatProviderResponse'
'500':
description: failed to write config to database
/v1/admin/users/identities:
get:
tags:
- Onramp-Offramp
summary: Get a list of User Identities
description: Get a list of user identities
operationId: list_identities
parameters:
- name: page
schema:
description: Page number for paginated results
type: integer
in: query
style: form
- name: page_size
schema:
description: Page size for paginated results
type: integer
in: query
style: form
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListUserIdentitiesResponse'
'500':
description: |-
Possible reasons:
- database error
- failed to get fiat ramp configuration
- failed to build fiat ramp configuration
/v1/users/{id}/identity:
get:
tags:
- Onramp-Offramp
summary: Get a User Identity
description: Get the identity for a user
operationId: get_identity
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetIdentityResponse'
'500':
description: |-
Possible reasons:
- database error
- failed to get fiat ramp configuration
- failed to build fiat ramp configuration
- failed to get fiat ramp identity
'404':
description: no identity for user
post:
tags:
- Onramp-Offramp
summary: Create or Update an Identity
description: Create or update an identity and optionally attach identity documents.
operationId: set_identity
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SetIdentityRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SetIdentityResponse'
'500':
description: |-
Possible reasons:
- database error
- database error
- failed to get fiat ramp configuration
- failed to build fiat ramp configuration
- failed to set identity
- failed to upload identity document
'404':
description: unknown user
delete:
tags:
- Onramp-Offramp
summary: Delete a User Identity
description: Delete the identity for a user
operationId: delete_identity
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EmptyResponse'
'500':
description: |-
Possible reasons:
- database error
- failed to get fiat ramp configuration
- failed to build fiat ramp configuration
- failed to delete fiat ramp identity
- database error
'404':
description: no identity for user
/v1/users/{id}/identity/tos:
get:
tags:
- Onramp-Offramp
summary: Get a User TOS Link
description: Get the tos_link for a user
operationId: get_tos_link
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetTosLinkResponse'
'500':
description: database error
'404':
description: no identity for user
/v1/users/{id}/transactions/fiat-ramp/onramp:
post:
tags:
- Onramp-Offramp
summary: Initiate a Fiat Deposit
description: Initiate a fiat deposit for a given fiat currency, country, and asset.
operationId: initiate_deposit
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/InitiateDepositRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/InitiateDepositResponse'
'400':
description: |-
Possible reasons:
- could not parse amount: {body.amount}
- identity must accept terms of service
- unknown asset_code
- vendor asset not configured for fiat ramp
- onramp transaction with this external_id was already attempted
'500':
description: |-
Possible reasons:
- database error
- database error
- failed to get to asset_code
- failed to get asset code
- database error
- failed to get fiat ramp configuration
- failed to build fiat ramp configuration
- failed to set up asset for user
- failed to execute deposit
- database error
- database error
- database error
'404':
description: |-
Possible reasons:
- unknown user
- user identity not found
/v1/users/{id}/transactions/fiat-ramp/offramp:
post:
tags:
- Onramp-Offramp
summary: Initiate a Fiat Withdrawal
description: Initiate a fiat withdraw for a given fiat currency, country, and asset.
operationId: initiate_withdraw
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/InitiateWithdrawRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/InitiateWithdrawResponse'
'400':
description: |-
Possible reasons:
- could not parse amount: {body.amount}
- identity must accept terms of service
- unknown asset_code
- vendor asset not configured for fiat ramp
- offramp transaction with this external_id was already attempted
- no payment instruction found
'500':
description: |-
Possible reasons:
- database error
- database error
- failed to get to asset_code
- failed to get asset code
- database error
- database error
- failed to get fiat ramp configuration
- failed to build fiat ramp configuration
- failed to set up asset for user
- failed to execute withdraw
- database error
- database error
- database error
'404':
description: |-
Possible reasons:
- unknown user
- user identity not found
/v1/users/{id}/transactions/fiat-ramp/{txn_id}:
get:
tags:
- Onramp-Offramp
summary: Get a Fiat Transaction
description: Get a fiat transaction by ID
operationId: get_transaction
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
- name: txn_id
required: true
schema:
type: string
format: uuid
in: path
style: simple
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/FiatRampTransaction'
'403':
description: access denied
'500':
description: |-
Possible reasons:
- database error
- failed to convert transaction
'404':
description: transaction not found
/v1/users/{id}/transactions/fiat-ramp:
get:
tags:
- Onramp-Offramp
summary: List Fiat Transactions
description: List fiat transactions for a user
operationId: list_transactions
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
- name: page
schema:
description: Page number for paginated results
type: integer
in: query
style: form
- name: page_size
schema:
description: Page size for paginated results
type: integer
in: query
style: form
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListFiatRampTransactionsResponse'
'500':
description: |-
Possible reasons:
- database error
- failed to convert transactions
/v1/users/{id}/payment-instructions:
get:
tags:
- Onramp-Offramp
summary: Get payment instructions
operationId: get_payment_instructions
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetPaymentInstructionsResponse'
'500':
description: |-
Possible reasons:
- database error
- database error
- failed to get fiat ramp configuration
- failed to build fiat ramp configuration
- database error
- failed to get payment instructions
'404':
description: |-
Possible reasons:
- unknown user
- user identity not found
post:
tags:
- Onramp-Offramp
summary: Add payment instruction
description: Add a new payment instruction to a user's identity
operationId: add_payment_instructions
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentInstructionCreateDto'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AddPaymentInstructionResponse'
'400':
description: user must already have an identity
'500':
description: |-
Possible reasons:
- database error
- database error
- failed to get fiat ramp configuration
- failed to build fiat ramp configuration
- failed to add payment instruction
- database error
'404':
description: unknown user
/v1/network/fiat-quote:
get:
tags:
- Onramp-Offramp
summary: Get a quote for onramp or offramp
description: Get a quote for onramp or offramp
operationId: get_quote
parameters:
- name: txnType
schema:
$ref: '#/components/schemas/FiatRampTxnType'
in: query
style: form
- name: countryCode
schema:
$ref: '#/components/schemas/CountryCode'
in: query
style: form
- name: fiatCurrency
schema:
$ref: '#/components/schemas/FiatCurrencyId'
in: query
style: form
- name: assetCode
schema:
description: Asset code
type: string
in: query
style: form
- name: paymentMethod
schema:
$ref: '#/components/schemas/PaymentMethod'
in: query
style: form
- name: fromAmount
schema:
nullable: true
description: From amount of the conversion, e.g 100.
type: string
in: query
style: form
- name: toAmount
schema:
nullable: true
description: To amount of the conversion, e.g 100.
type: string
in: query
style: form
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetQuoteResponse'
'400':
description: |-
Possible reasons:
- either to_amount or from_amount should be specified
- vendor asset not configured for fiat ramp
'500':
description: |-
Possible reasons:
- failed to get asset code
- failed to get fiat ramp configuration
- failed to build fiat ramp configuration
'412':
description: ''
/v1/payment-options:
post:
tags:
- Onramp-Offramp
summary: Get payment options for onramp
operationId: get_payment_options
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OptionsRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OptionsResponse'
'500':
description: |-
Possible reasons:
- failed to get OnOff ramp configuration
- OnOff ramp error
/v1/withdrawal-options:
post:
tags:
- Onramp-Offramp
summary: Get withdrawal options for offramp
operationId: get_withdrawal_options
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OptionsRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OptionsResponse'
'500':
description: |-
Possible reasons:
- failed to get OnOff ramp configuration
- OnOff ramp error
/v1/stake:
post:
tags:
- Stake
summary: Stake Assets via Service Provider
description: Stakes assets using configured service provider
operationId: stake
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/StakeRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/StakeResponse'
'400':
description: |-
Possible reasons:
- incorrect address format
- incorrect amount
- unable to parse vault_id
- asset_code not found
- network needs to be configured for this asset_code
- asset_code not found
- incorrect amount
'500':
description: "Possible reasons:\n- service not configured to support staking\n- unable to connect to database\n- configured network is not supported\n- unable to connect to database\n- unable to obtain vault info\n- vault does not contain asset_code\n- unable to parse available amount\n- \n- bd post stake intent failed\n- unable to create transaction"
/v1/unstake:
post:
tags:
- Stake
summary: Unstake Assets via Service Provider
description: Unstakes assets using configured service provider
operationId: unstake
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UnstakeRequest'
required: true
responses:
'400':
description: |-
Possible reasons:
- asset_code not found
- network needs to be configured for this asset_code
'500':
description: |-
Possible reasons:
- service not configured to support staking
- unable to connect to database
- configured network is not supported
- bd post unstake intent failed
/v1/external-addresses:
get:
tags:
- External Addresses
summary: List Registered External Addresses
description: Get list of the registered external addresses.
operationId: list_external_addresses
parameters:
- name: page
schema:
description: Page number for paginated results
type: integer
in: query
style: form
- name: page_size
schema:
description: Page size for paginated results
type: integer
in: query
style: form
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ExternalAddress'
'400':
description: failed to get external addresses
post:
tags:
- External Addresses
summary: Register New External Address
description: Register a new external address. Creates a new Knova wallet in the custodial wallet service.
operationId: set_external_address
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateExternalAddressRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalAddress'
'500':
description: failed to save address in database
/v1/products:
get:
tags:
- Products
summary: Supported products
description: List supported products
operationId: get_products
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/GetProductsResponse'
/v1/users/{id}/product/{product}/buy:
post:
tags:
- Products
summary: Buy
description: Buy
operationId: buy
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
- name: product
required: true
schema:
type: string
in: path
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BuyRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BuyResponse'
'400':
description: |-
Possible reasons:
- incorrect amount
- failed to initiate buy product
'500':
description: failed to get user from database
'404':
description: |-
Possible reasons:
- check /products for supported options
- unknown user
/v1/users/{id}/product/{product}/sell:
post:
tags:
- Products
summary: Sell
description: Sell
operationId: sell
parameters:
- name: id
required: true
schema:
type: string
format: uuid
in: path
style: simple
- name: product
required: true
schema:
type: string
in: path
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SellRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SellResponse'
'400':
description: "Possible reasons:\n- incorrect amount\n- token_asset_code not found\n- \n- base_asset_code not found\n- \n- asset_code not found"
'500':
description: |-
Possible reasons:
- failed to get user from database
- unable to connect to database
- unable to connect to database
- unable to connect to database
- failed to serialize product approve
- failed to serialize teller sell
- failed to get authority public key
- failed to create transaction
'404':
description: |-
Possible reasons:
- check /products for supported options
- unknown user
components:
schemas:
Action:
oneOf:
- type: object
properties:
to_ratio:
type: string
address:
type: string
type:
type: string
enum:
- rebalance_to_ratio
required:
- to_ratio
- address
- type
- type: object
properties:
amount:
type: string
format: decimal
to_address:
type: string
to_tag_memo:
nullable: true
type: string
type:
type: string
enum:
- withdraw_to_address
required:
- amount
- to_address
- type
- type: object
properties:
amount:
nullable: true
description: |-
Amount of asset to purchase, e.g. "1000.0". Only either `amount` or `residual_balance`
should be populated.
type: string
format: decimal
residual_balance:
nullable: true
description: The desired balance of the purchasing token (e.g. "USDC_ETH") after purchasing the asset, e.g. "0.0".
type: string
format: decimal
base_asset_code:
description: The asset code of the base asset, e.g. "ETH".
type: string
token_asset_code:
description: The asset code of the token asset to spend, e.g. "USDC_ETH".
type: string
type:
type: string
enum:
- buy_product
required:
- base_asset_code
- token_asset_code
- type
- type: object
properties:
vendor:
$ref: '#/components/schemas/CustodyVendor'
asset_code:
description: Asset code of asset to sweep, e.g. "USDC_ETH".
type: string
threshold_balance:
description: The sweep is triggered if the vault balance is greater than the threshold, e.g. "0.0".
type: string
format: decimal
residual_balance:
nullable: true
description: The desired balance of the vault after having been swept, e.g. "0.0"
type: string
format: decimal
base_asset_code:
nullable: true
description: Asset of base asset, e.g. ETH. Only needed for non-base assets.
type: string
base_threshold_balance:
nullable: true
description: The funding of the base asset is triggered if the vault balance is below the threshold, e.g. "0.01".
type: string
format: decimal
base_fund_amount:
nullable: true
description: Base asset amount to send to the vault when funding, e.g. "0.05".
type: string
format: decimal
type:
type: string
enum:
- sweep_customers_to_omnibus
required:
- vendor
- asset_code
- threshold_balance
- type
AddPaymentInstructionResponse:
type: object
properties:
payment_instruction_id:
description: ID of the payment instruction
type: string
format: uuid
required:
- payment_instruction_id
Address:
type: object
properties:
address:
description: Blockchain address
type: string
tag_memo:
nullable: true
description: Optional tag or memo for the address
type: string
required:
- address
AddressInfo:
type: object
properties:
asset_code:
description: Asset code (e.g. BTC)
type: string
address:
description: Address of the user
type: string
required:
- asset_code
- address
AllUsersAssetsResponse:
type: object
properties:
id:
description: ID of the user
type: string
format: uuid
username:
description: Name of the user
type: string
verifier:
description: Wallet verifier of the user
type: string
user_type:
description: Type of the user
type: string
address_info:
description: Address information of the user
type: array
items:
$ref: '#/components/schemas/AddressInfo'
required:
- id
- username
- verifier
- user_type
- address_info
AllVendorAssetBalanceParams:
type: object
properties:
page:
description: Page number for paginated results
type: integer
page_size:
description: Page size for paginated results
type: integer
vendors:
description: Optional list of vendors to filter by
type: array
items:
$ref: '#/components/schemas/CustodyVendor'
required:
- page
- page_size
- vendors
AllVendorAssetBalanceResponse:
type: object
properties:
vendor:
description: Vendor holding the asset
type: string
asset_code:
description: Standard non-vendor specific Asset code (e.g. BTC)
type: string
asset_vendor_code:
description: Vendor-specific asset code (e.g. BTC_TEST)
type: string
balance:
description: Asset code balance
type: string
format: decimal
required:
- vendor
- asset_code
- asset_vendor_code
- balance
ApprovalRequest:
type: object
properties:
uetr:
type: string
format: uuid
idempotency_key:
type: string
format: uuid
created:
type: string
format: date-time
required:
- uetr
- idempotency_key
- created
ApprovalRequestWebhookPayload:
type: object
properties:
uetr:
description: The unique identifier for the approval request
type: string
format: uuid
idempotency_key:
description: The idempotency key associated with the approval request
type: string
format: uuid
required:
- uetr
- idempotency_key
AssetBalanceListParams:
type: object
properties:
asset_code:
nullable: true
description: Asset code (e.g. BTC)
type: string
page:
description: Page number for paginated results
type: integer
page_size:
description: Page size for paginated results
type: integer
required:
- page
- page_size
AssetCode:
type: object
properties:
asset_code:
description: |-
Code of asset (e.g. BTC). The code is arbitrary and configurable by admins. It is the code
to use in subsequent API requests.
type: string
requires_customer_vault:
description: |-
Indicates that the asset is account-based, thus requiring deposits to go to separate customer
vaults in order to correlate the deposit to users.
type: boolean
decimals:
description: Number of decimals for asset (e.g. 18).
type: integer
base_asset:
nullable: true
description: If set, indicates the base asset code that this asset is based on.
type: string
network:
nullable: true
description: Optional name of the network (e.g. hoodi).
type: string
explorer_url:
nullable: true
description: Optional URL to blockchain explorer for this asset.
type: string
vendor_codes:
description: Map of vendors to the vendor-specific code for the asset (e.g. ETH_TEST5).
type: object
additionalProperties:
type: string
required:
- asset_code
- requires_customer_vault
- decimals
- vendor_codes
AssetCodeInput:
type: object
properties:
asset_code:
description: Asset code (e.g. BTC)
type: string
required:
- asset_code
AssetRestrictions:
type: object
properties:
asset_code:
description: Asset code the restrictions apply to
type: string
role:
description: Role the restrictions apply to
type: string
max_maker_amount:
nullable: true
description: Maximum maker amount allowed for the user
type: string
required:
- asset_code
- role
AssetTotalBalance:
type: object
properties:
asset_code:
description: Asset code (e.g. BTC)
type: string
base_asset:
nullable: true
description: If set, indicates the base asset code that this asset is based on
type: string
holders:
description: Number of holders of this asset
type: integer
total_amount:
description: Total amount of this asset held by all users
type: string
format: decimal
required:
- asset_code
- holders
- total_amount
Automation:
type: object
properties:
id:
description: ID of the automation
type: string
format: uuid
name:
description: Name of the automation
type: string
trigger:
$ref: '#/components/schemas/Trigger'
condition:
$ref: '#/components/schemas/Condition'
action:
$ref: '#/components/schemas/Action'
trigger_description:
description: Description of the `Trigger`
type: string
condition_description:
description: Description of the `Condition`
type: string
action_description:
description: Description of the `Action`
type: string
status:
$ref: '#/components/schemas/AutomationStatus'
next_run:
nullable: true
description: When the automation is next scheduled to run
type: string
format: date-time
last_run:
nullable: true
description: When the automation last ran
type: string
format: date-time
user_id:
nullable: true
description: The creating user id
type: string
format: uuid
required:
- id
- name
- trigger
- condition
- action
- trigger_description
- condition_description
- action_description
- status
AutomationRun:
type: object
properties:
id:
description: ID of the automation run
type: string
format: uuid
scheduled:
description: When the automation was scheduled to run
type: string
format: date-time
started:
description: When the automation started running
type: string
format: date-time
finished:
nullable: true
description: When the automation finished running
type: string
format: date-time
success:
nullable: true
description: Whether the automation run was successful
type: boolean
error:
nullable: true
description: Error message if the automation run failed
type: string
required:
- id
- scheduled
- started
AutomationStatus:
type: string
enum:
- Active
- Running
- Disabled
Balance:
type: object
properties:
asset_code:
description: Asset code (e.g. BTC)
type: string
amount:
description: Amount of the asset
type: string
format: decimal
required:
- asset_code
- amount
BankAccountNumberType:
type: string
enum:
- CVU
- CBU
- ALIAS
BankAccountOwnerType:
type: string
enum:
- Personal
- Business
BankAccountType:
type: string
enum:
- Checking
- Savings
BankDetailsCreateDto:
type: object
properties:
bankCode:
nullable: true
description: The bank code for the account, such as a routing number or sort code.
type: string
bankSlug:
nullable: true
description: The bank code for the account, such as a routing number or sort code
type: string
bankAccountNumber:
description: The bank account number
type: string
address:
$ref: '#/components/schemas/PostalAddressCreateDto'
bankName:
nullable: true
description: The name of the bank.
type: string
phone:
nullable: true
description: The phone number associated with the bank account.
type: string
taxId:
nullable: true
description: The tax identification number associated with the account.
type: string
accountHolderName:
nullable: true
description: The name of the account holder. Required for Colombia. Learn more at [Payment Instructions Guide](https://docs.buildborderless.com/docs/latam-payment-instructions).
type: string
bankAccountType:
$ref: '#/components/schemas/BankAccountType'
bankAccountNumberType:
$ref: '#/components/schemas/BankAccountNumberType'
required:
- bankAccountNumber
- address
BankDetailsEntity:
type: object
properties:
bankName:
nullable: true
type: string
bankSlug:
nullable: true
type: string
bankAccountNumberLast4:
type: string
bankRoutingNumber:
nullable: true
type: string
bankCode:
nullable: true
type: string
phone:
nullable: true
type: string
taxId:
nullable: true
type: string
accountHolderName:
nullable: true
type: string
bankAccountType:
$ref: '#/components/schemas/BankAccountType'
address:
$ref: '#/components/schemas/PostalAddressEntity'
required:
- bankAccountNumberLast4
BurnRequest:
type: object
properties:
external_id:
description: Unique ID to ensure idempotency.
type: string
asset_code:
description: Code of asset to transfer.
type: string
amount:
description: Amount to transfer.
type: string
format: decimal
fee_level:
$ref: '#/components/schemas/FeeLevel'
memo:
nullable: true
description: Optional memo to attach to transaction.
type: string
required:
- external_id
- asset_code
- amount
- fee_level
BurnResponse:
type: object
properties:
id:
description: Burn transaction ID.
type: string
format: uuid
required:
- id
BusinessOperation:
type: string
enum:
- client
- parent company
- subsidiary
- supplier
BusinessPurposeOfFunds:
type: string
enum:
- intra group transfer
- invoice for goods and services
BuyRequest:
type: object
properties:
external_id:
type: string
base_asset_code:
type: string
token_asset_code:
type: string
amount:
type: string
required:
- external_id
- base_asset_code
- token_asset_code
- amount
BuyResponse:
type: object
properties:
id:
type: string
format: uuid
required:
- id
CardDetailsEntity:
type: object
properties:
id:
nullable: true
type: string
CloseTradeResponse:
type: object
properties:
id:
nullable: true
description: Trade Fill ID
type: string
format: uuid
ComplianceStatus:
type: string
enum:
- Active
- Inactive
- Suspended
Condition:
oneOf:
- type: object
properties:
user_id:
type: string
format: uuid
asset_code:
type: string
threshold_balance:
description: |-
Threshold balance - value of 1000.0 indicates that this triggers if the user balance is
greater than 1000.0 for this asset code.
type: string
format: decimal
type:
type: string
enum:
- user_balance_greater_than
required:
- user_id
- asset_code
- threshold_balance
- type
- type: object
properties:
user_id:
type: string
format: uuid
asset_code:
type: string
threshold_balance:
description: |-
Threshold balance - value of 1000.0 indicates that this triggers if the user balance is
below 1000.0 for this asset code.
type: string
format: decimal
type:
type: string
enum:
- user_balance_less_than
required:
- user_id
- asset_code
- threshold_balance
- type
- type: object
properties:
asset_code:
type: string
vendor:
$ref: '#/components/schemas/CustodyVendor'
vault_id:
type: string
reference_vendor:
$ref: '#/components/schemas/CustodyVendor'
reference_vault_id:
type: string
threshold_ratio:
description: |-
Threshold ratio - ratio of 0.3 indicates that this triggers if the vault balance is
greater than 30% of the sum of it and the reference vault balance.
type: string
type:
type: string
enum:
- vault_balance_ratio_greater_than
required:
- asset_code
- vendor
- vault_id
- reference_vendor
- reference_vault_id
- threshold_ratio
- type
- type: object
properties:
type:
type: string
enum:
- any
required:
- type
ContractTransaction:
type: object
properties:
id:
description: Id of contract transaction
type: string
format: uuid
external_id:
nullable: true
description: Idemopotency key used for the transaction
type: string
external_transactions:
description: List of external transactions
type: array
items:
$ref: '#/components/schemas/ExternalTransaction'
digital_twin_transactions:
description: List of digital twin transactions
type: array
items:
$ref: '#/components/schemas/DigitalTwinTransaction'
digital_twin_summary:
description: Summary of digital twin asset changes per user
type: object
additionalProperties:
type: object
additionalProperties:
type: string
format: decimal
contract_type:
$ref: '#/components/schemas/ContractType'
status:
description: Status of the contract transaction
type: string
memo:
nullable: true
description: Optional memo attached to the contract
type: string
created:
description: Timestamp when the transaction was created
type: string
format: date-time
required:
- id
- external_transactions
- digital_twin_transactions
- digital_twin_summary
- contract_type
- status
- created
ContractTransactionBlock:
type: object
properties:
id:
description: Id of contract transaction
type: string
format: uuid
operation:
description: Name of operation
type: string
operation_idx:
description: Index of operation
type: integer
previous_block_hash:
nullable: true
description: Previous block hash
type: string
signature:
nullable: true
description: Signature of block
type: string
idempotency_key:
nullable: true
description: Idemopotency key used for block
type: string
func_name:
nullable: true
description: Name of adapter function called by block
type: string
data:
description: Data in JSON format
type: object
created:
description: Timestamp when block was created
type: string
format: date-time
required:
- id
- operation
- operation_idx
- data
- created
ContractType:
type: string
enum:
- Withdraw
- Deposit
- Mint
- Burn
- Trade
- Transfer
- Issue
- Redeem
- Other
CoreTxnStatus:
type: string
enum:
- Pending
- Completed
- Failed
CountryCode:
type: string
enum:
- AF
- AL
- DZ
- AS
- AD
- AO
- AI
- AQ
- AG
- AR
- AM
- AW
- AU
- AT
- AZ
- BS
- BH
- BD
- BB
- BY
- BE
- BZ
- BJ
- BM
- BT
- BO
- BQ
- BA
- BW
- BV
- BR
- IO
- BN
- BG
- BF
- BI
- CV
- KH
- CM
- CA
- KY
- CF
- TD
- CL
- CN
- CX
- CC
- CO
- KM
- CD
- CG
- CK
- CR
- HR
- CU
- CW
- CY
- CZ
- CI
- DK
- DJ
- DM
- DO
- EC
- EG
- SV
- GQ
- ER
- EE
- SZ
- ET
- FK
- FO
- FJ
- FI
- FR
- GF
- PF
- TF
- GA
- GM
- GE
- DE
- GH
- GI
- GR
- GL
- GD
- GP
- GU
- GT
- GG
- GN
- GW
- GY
- HT
- HM
- VA
- HN
- HK
- HU
- IS
- IN
- ID
- IR
- IQ
- IE
- IM
- IL
- IT
- JM
- JP
- JE
- JO
- KZ
- KE
- KI
- KP
- KR
- KW
- KG
- LA
- LV
- LB
- LS
- LR
- LY
- LI
- LT
- LU
- MO
- MG
- MW
- MY
- MV
- ML
- MT
- MH
- MQ
- MR
- MU
- YT
- MX
- FM
- MD
- MC
- MN
- ME
- MS
- MA
- MZ
- MM
- NA
- NR
- NP
- NL
- NC
- NZ
- NI
- NE
- NG
- NU
- NF
- MP
- NO
- OM
- PK
- PW
- PS
- PA
- PG
- PY
- PE
- PH
- PN
- PL
- PT
- PR
- QA
- MK
- RO
- RU
- RW
- RE
- BL
- SH
- KN
- LC
- MF
- PM
- VC
- WS
- SM
- ST
- SA
- SN
- RS
- SC
- SL
- SG
- SX
- SK
- SI
- SB
- SO
- ZA
- GS
- SS
- ES
- LK
- SD
- SR
- SJ
- SE
- CH
- SY
- TW
- TJ
- TZ
- TH
- TL
- TG
- TK
- TO
- TT
- TN
- TR
- TM
- TC
- TV
- UG
- UA
- AE
- GB
- UM
- US
- UY
- UZ
- VU
- VE
- VN
- VG
- VI
- WF
- EH
- YE
- ZM
- ZW
- AX
CreateAddressRequest:
type: object
properties:
asset_code:
description: Asset code (e.g. BTC)
type: string
vendor:
$ref: '#/components/schemas/CustodyVendor'
required:
- asset_code
CreateExternalAddressRequest:
type: object
properties:
name:
description: Name for the external address
type: string
address:
description: The external address (e.g. blockchain address)
type: string
tag_memo:
nullable: true
description: Optional tag or memo for the external address
type: string
required:
- name
- address
CreateMarketMakerRequest:
type: object
properties:
name:
description: Name of the market maker to create
type: string
required:
- name
CreateWebhookSubscriptionRequest:
type: object
properties:
url:
description: URL where to send webhook notifications
type: string
active:
description: Indicate if is active (notifications get sent to URL)
type: boolean
required:
- url
- active
CustodyVendor:
type: string
enum:
- Fireblocks
- Blockdaemon
- Stripe
DeleteAssetRestrictionsRequest:
type: object
properties:
asset_code:
description: Asset code the restrictions apply to
type: string
role:
description: Role the restrictions apply to
type: string
required:
- asset_code
- role
DeleteWebhookSubscriptionRequest:
type: object
properties:
id:
description: ID of the webhook subscription to delete
type: string
format: uuid
required:
- id
DigitalTwinTransaction:
type: object
properties:
to:
nullable: true
description: User id receiving the assets
type: string
format: uuid
to_username:
nullable: true
description: Username of user receiving the assets
type: string
from:
nullable: true
description: User id sending the assets
type: string
format: uuid
from_username:
nullable: true
description: Username of user sending the assets
type: string
asset_code:
description: Asset code (e.g. BTC)
type: string
amount:
description: Amount of the asset sent or received
type: string
format: decimal
action_type:
$ref: '#/components/schemas/DigitalTwinTransactionType'
description:
nullable: true
description: Description of the action
type: string
required:
- asset_code
- amount
- action_type
DigitalTwinTransactionType:
type: string
enum:
- Issue
- Redeem
- Transfer
EmploymentStatus:
type: string
enum:
- Employed
- Homemaker
- Retired
- SelfEmployed
- Student
- Unemployed
EmptyResponse:
type: object
EstimatedNetworkFees:
type: object
properties:
asset_code:
description: Asset code (e.g., BTC)
type: string
low:
$ref: '#/components/schemas/NetworkFees'
medium:
$ref: '#/components/schemas/NetworkFees'
high:
$ref: '#/components/schemas/NetworkFees'
required:
- asset_code
- low
- medium
- high
EthereumStakeData:
type: object
properties:
id:
description: Unique stake identifier.
type: string
amount:
description: Amount of ETH (denominated in Gwei).
type: string
validator_public_key:
description: A BLS public Key.
type: string
withdrawal_credentials:
description: |-
Hexadecimal encoded [withdrawal credentials](https://github.com/ethereum/consensus-specs/blob/master/specs/phase0/validator.md#withdrawal-credentials)
which can be either a BLS public key or an Ethereum account address. This parameter currently accepts ETH1 and BLS withdrawal credentials, but it is
considered deprecated after the Capella/Shanghai fork. All users are now advised to use an ETH1 withdrawal address, specified through the
`withdrawal_address` parameter as this is required to enable the ongoing accrual of rewards.
For more information regarding creating withdrawal credentials, please see the official
[Ethereum Launchpad FAQ](https://launchpad.ethereum.org/en/faq#withdrawal-credentials).
type: string
fee_recipient:
description: An Ethereum address to receive transaction fees from published blocks. 20-bytes, hex encoded with 0x prefix, case insensitive.
type: string
required:
- id
- amount
- validator_public_key
- withdrawal_credentials
- fee_recipient
EventType:
type: string
enum:
- ApprovalRequest
- ContractTransaction
ExternalAddress:
type: object
properties:
id:
description: ID of the external address
type: string
format: uuid
name:
description: Name of the external address
type: string
address:
description: Blockchain address
type: string
tag_memo:
nullable: true
description: Optional tag or memo associated with the address
type: string
created:
description: Timestamp when the external address was created
type: string
format: date-time
required:
- id
- name
- address
- created
ExternalTransaction:
type: object
properties:
OnchainTransaction:
type: object
properties:
to:
$ref: '#/components/schemas/Address'
from:
$ref: '#/components/schemas/Address'
asset_code:
description: Asset code (e.g. BTC)
type: string
amount:
description: Amount of the asset sent or received
type: string
format: decimal
fee_asset_code:
description: Asset code used to pay transaction fees (e.g. BTC)
type: string
network_fee:
description: Amount of the transaction fees
type: string
format: decimal
fee_level:
$ref: '#/components/schemas/FeeLevel'
status:
$ref: '#/components/schemas/OnchainTransactionStatus'
substatus:
nullable: true
description: Secondary status on the transaction
type: string
tx_hash:
nullable: true
description: Transaction hash of the onchain transaction
type: string
created:
description: Timestamp when the transaction was created
type: string
format: date-time
required:
- asset_code
- amount
- fee_asset_code
- network_fee
- status
- created
required:
- OnchainTransaction
Fee:
oneOf:
- type: object
properties:
level:
$ref: '#/components/schemas/FeeLevel'
fee_type:
type: string
enum:
- base
required:
- level
- fee_type
- type: object
properties:
level:
$ref: '#/components/schemas/FeeLevel'
fee_amount:
nullable: true
description: |-
The amount that the customer pays in fees in the given `asset_code` in return for the
treasury paying the gas.
type: string
fee_type:
type: string
enum:
- non_base
required:
- level
- fee_type
FeeLevel:
type: string
enum:
- LOW
- MEDIUM
- HIGH
FiatCurrencyId:
type: string
enum:
- USD
- EUR
- BRL
- ARS
- MXN
- COP
- CLP
- PEN
- BWP
- CDF
- GHS
- KES
- MWK
- NGN
- RWF
- ZAR
- TZS
- UGX
- ZMW
- XOF
- XAF
FiatProvider:
description: Fiat Provider for a user
type: object
properties:
customer:
description: Customer ID (i.e. cus_*)
type: string
payin_payment_method:
description: Payment method (i.e. pm_*)
type: string
payin_payment_method_type:
description: Payment method type (i.e. us_bank_account, debit, etc.)
type: string
payout_account:
description: Payout account (i.e. acct_*)
type: string
payout_method:
description: Payout method (i.e. usba_*)
type: string
required:
- customer
- payin_payment_method
- payin_payment_method_type
- payout_account
- payout_method
FiatRampTransaction:
type: object
properties:
id:
type: string
format: uuid
userId:
type: string
format: uuid
externalId:
type: string
fiatCurrency:
$ref: '#/components/schemas/FiatCurrencyId'
assetCode:
type: string
amount:
type: string
format: decimal
txnType:
$ref: '#/components/schemas/FiatRampTxnType'
txnStatus:
type: string
paymentMethod:
$ref: '#/components/schemas/PaymentMethod'
paymentInstructions:
nullable: true
type: object
paymentPurpose:
$ref: '#/components/schemas/PaymentPurpose'
paymentInstructionsId:
nullable: true
type: string
format: uuid
created:
type: string
format: date-time
updated:
type: string
format: date-time
required:
- id
- userId
- externalId
- fiatCurrency
- assetCode
- amount
- txnType
- txnStatus
- created
- updated
FiatRampTxnType:
type: string
enum:
- OnRamp
- OffRamp
FiatTxnRequest:
type: object
properties:
external_id:
description: Unique ID to ensure idempotency
type: string
asset_code:
description: Code of asset to transfer
type: string
to:
description: The user_id to transfer assets to
type: string
format: uuid
amount:
description: The total `amount` to be sent by the customer
type: string
format: decimal
memo:
nullable: true
description: Optional memo attached to the contract
type: string
required:
- external_id
- asset_code
- to
- amount
FiatTxnResponse:
type: object
properties:
id:
description: Fiat transaction ID
type: string
format: uuid
required:
- id
FundMarketMakerRequest:
type: object
properties:
asset_code:
description: Asset code (e.g. BTC)
type: string
amount:
description: Amount of asset to fund market maker with
type: string
format: decimal
required:
- asset_code
- amount
FundingType:
type: string
enum:
- InitialFunding
- Refund
GetAutomationCapabilitiesResponse:
type: object
properties:
capabilities:
description: |-
Automation capabilities as a list of valid combinations of triggers, conditions, and
actions
type: array
items:
type: array
items:
type: string
required:
- capabilities
GetContractTransactionBlocksResponse:
type: object
properties:
blocks:
type: array
items:
$ref: '#/components/schemas/ContractTransactionBlock'
required:
- blocks
GetIdentityResponse:
type: object
properties:
id:
description: Id of the user
type: string
format: uuid
username:
description: Username of the user
type: string
identity:
$ref: '#/components/schemas/Identity'
required:
- id
- username
- identity
GetPaymentInstruction:
type: object
properties:
id:
description: The internal ID, not the vendor ID
type: string
name:
description: A unique identifier for a payment instruction, allowing to distinguish it from other accounts.
type: string
paymentMethod:
$ref: '#/components/schemas/PaymentMethod'
currency:
description: The fiat currency for the payment instructions.
type: string
country:
$ref: '#/components/schemas/CountryCode'
deleted:
description: Indicates if payment instructions have been deleted.
type: boolean
required:
- id
- name
- paymentMethod
- currency
- country
- deleted
GetPaymentInstructionsResponse:
type: object
properties:
paymentInstructions:
description: List of payment instructions
type: array
items:
$ref: '#/components/schemas/GetPaymentInstruction'
required:
- paymentInstructions
GetProductsResponse:
type: object
properties:
products:
description: List of supported products
type: array
items:
type: string
required:
- products
GetQuoteParams:
type: object
properties:
txnType:
$ref: '#/components/schemas/FiatRampTxnType'
countryCode:
$ref: '#/components/schemas/CountryCode'
fiatCurrency:
$ref: '#/components/schemas/FiatCurrencyId'
assetCode:
description: Asset code
type: string
paymentMethod:
$ref: '#/components/schemas/PaymentMethod'
fromAmount:
nullable: true
description: From amount of the conversion, e.g 100.
type: string
toAmount:
nullable: true
description: To amount of the conversion, e.g 100.
type: string
required:
- txnType
- countryCode
- fiatCurrency
- assetCode
GetQuoteResponse:
type: object
properties:
fromAmount:
description: From amount of the conversion, e.g 100.
type: string
toAmount:
description: To amount of the conversion, e.g 100.
type: string
exchangeRate:
description: Exchange rate of the conversion, e.g 1.
type: string
totalFee:
description: Total fees.
type: string
required:
- fromAmount
- toAmount
- exchangeRate
- totalFee
GetTosLinkResponse:
type: object
properties:
id:
description: Id of the user
type: string
format: uuid
tos_link:
description: Link to the Terms of Service acceptance form
type: string
tos_accepted:
description: Indicate if the Terms of Service has been accepted
type: boolean
required:
- id
- tos_link
- tos_accepted
GetTradeQuoteRequest:
type: object
properties:
external_id:
description: Unique ID to ensure idempotency
type: string
from_asset_code:
description: Code of asset to sell
type: string
from_amount:
description: The total `amount` to be sold
type: string
format: decimal
to_asset_code:
description: Code of asset to buy
type: string
required:
- external_id
- from_asset_code
- from_amount
- to_asset_code
GetTradeQuoteResponse:
type: object
properties:
quote_id:
description: Quote ID
type: string
to_amount:
description: To amount
type: string
format: decimal
expires:
nullable: true
description: Timestamp when quote expires
type: string
format: date-time
required:
- quote_id
- to_amount
GetTransactionFeeRequest:
type: object
properties:
asset_code:
description: Asset code (e.g. BTC)
type: string
amount:
description: Amount of network transactions fees
type: string
format: decimal
required:
- asset_code
- amount
IdentifierDetailsCreateDto:
type: object
properties:
identifierType:
$ref: '#/components/schemas/PaymentInstructionIdentifierType'
identifierValue:
description: The value of the identifier, such as a PIX key or similar
type: string
phone:
nullable: true
description: The phone number associated with the identifier.
type: string
taxId:
nullable: true
description: The tax identification number associated with the identifier.
type: string
address:
$ref: '#/components/schemas/PostalAddressCreateDto'
required:
- identifierType
- identifierValue
- address
IdentifierDetailsEntity:
type: object
properties:
identifierType:
$ref: '#/components/schemas/PaymentInstructionIdentifierType'
identifierValue:
type: string
address:
$ref: '#/components/schemas/PostalAddressEntity'
required:
- identifierType
- identifierValue
- address
Identity:
type: object
properties:
firstName:
description: The first name
type: string
lastName:
description: The last name
type: string
secondLastName:
nullable: true
description: The second last name
type: string
middleName:
nullable: true
description: The middle name
type: string
taxId:
nullable: true
description: The tax identification number
type: string
dateOfBirth:
description: The date of birth in format yyyy-mm-dd
type: string
email:
nullable: true
description: The email address
type: string
phone:
nullable: true
description: The phone number
type: string
activity:
nullable: true
description: The activity or occupation
type: string
sex:
$ref: '#/components/schemas/Sex'
occupationCode:
$ref: '#/components/schemas/Occupations'
employmentStatus:
$ref: '#/components/schemas/EmploymentStatus'
sourceOfFunds:
$ref: '#/components/schemas/PersonalSourceOfFunds'
accountPurpose:
$ref: '#/components/schemas/PersonalAccountPurpose'
accountPurposeOther:
nullable: true
description: Other account purpose (required if accountPurpose is 'Other')
type: string
monthlyAmounts:
$ref: '#/components/schemas/MonthlyAmounts'
actingAsIntermediary:
nullable: true
description: Whether the person is acting as an intermediary for another party
type: boolean
address:
$ref: '#/components/schemas/PostalAddressEntity'
complianceStatus:
$ref: '#/components/schemas/ComplianceStatus'
documents:
description: List of identity documents
type: array
items:
$ref: '#/components/schemas/IdentityDocument'
required:
- firstName
- lastName
- dateOfBirth
- address
- complianceStatus
- documents
IdentityDocument:
type: object
properties:
id:
description: Document ID
type: string
issuingCountry:
$ref: '#/components/schemas/CountryCode'
documentType:
$ref: '#/components/schemas/IdentityDocumentType'
idNumber:
nullable: true
description: The document identification number
type: string
issuedDate:
nullable: true
description: The date the document was issued
type: string
format: date
expiryDate:
nullable: true
description: The date the document expires
type: string
format: date
required:
- id
- issuingCountry
- documentType
IdentityDocumentCreateDto:
type: object
properties:
issuingCountry:
$ref: '#/components/schemas/CountryCode'
type:
$ref: '#/components/schemas/IdentityDocumentType'
idNumber:
nullable: true
description: The document identification number, if applicable
type: string
issuedDate:
description: The date the document was issued in format yyyy-mm-dd
type: string
expiryDate:
nullable: true
description: The date the document expires in format yyyy-mm-dd, if applicable
type: string
imageFront:
nullable: true
description: 'The front side of the document in Base64 format. Supported MIME types (application/pdf, image/jpeg, image/jpg, image/png, image/heic, image/tiff). Minimum resolution: 200x200px, maximum size: 5MB. Refer to the [Business documents](https://docs.buildborderless.com/docs/business#/document-requirements-for-businesses-by-region) for region-specific requirements; refer to the [Personal documents](https://docs.buildborderless.com/docs/personal#/-supported-documents) for region-specific requirements.'
type: string
imageBack:
nullable: true
description: 'The back side of the document in Base64 format, if applicable. Supported MIME types (application/pdf, image/jpeg, image/jpg, image/png, image/heic, image/tiff). Minimum resolution: 200x200px, maximum size: 5MB. Refer to the [Business documents](https://docs.buildborderless.com/docs/business#/document-requirements-for-businesses-by-region) for region-specific requirements; refer to the [Personal documents](https://docs.buildborderless.com/docs/personal#/-supported-documents) for region-specific requirements.'
type: string
required:
- issuingCountry
- type
- issuedDate
IdentityDocumentType:
type: string
enum:
- Passport
- DriverLicense
- NationalId
- ResidencePermit
- Formation
- Ownership
- ProofOfAddress
InitiateDepositRequest:
type: object
properties:
externalId:
type: string
fiatCurrency:
$ref: '#/components/schemas/FiatCurrencyId'
countryCode:
$ref: '#/components/schemas/CountryCode'
assetCode:
type: string
amount:
type: string
paymentMethod:
$ref: '#/components/schemas/PaymentMethod'
required:
- externalId
- fiatCurrency
- countryCode
- assetCode
- amount
- paymentMethod
InitiateDepositResponse:
type: object
properties:
id:
description: Id of the deposit
type: string
format: uuid
required:
- id
InitiateInternalTxnRequest:
type: object
properties:
external_id:
description: Unique external ID for idempotency
type: string
asset_code:
description: Asset code for the transaction (e.g. BTC)
type: string
recipient_id:
description: User ID of the recipient
type: string
format: uuid
amount:
description: Amount of the asset to transfer
type: string
memo:
description: Optional memo for the transaction
type: string
required:
- external_id
- asset_code
- recipient_id
- amount
- memo
InitiateInternalTxnResponse:
type: object
properties:
id:
description: ID of the newly created internal transaction
type: string
format: uuid
required:
- id
InitiateOnchainTxnRequest:
type: object
properties:
external_id:
description: Unique ID to ensure idempotency
type: string
asset_code:
description: Code of asset to transfer
type: string
to:
$ref: '#/components/schemas/Address'
amount:
description: The total `amount` to be sent by the customer
type: string
format: decimal
fee:
$ref: '#/components/schemas/Fee'
required:
- external_id
- asset_code
- to
- amount
- fee
InitiateOnchainTxnResponse:
type: object
properties:
id:
description: Onchain transaction ID
type: string
format: uuid
required:
- id
InitiateTradeRequest:
type: object
properties:
external_id:
description: Unique ID to ensure idempotency.
type: string
from_asset_code:
description: Asset code to trade from (e.g. BTC)
type: string
to_asset_code:
description: Asset code to trade to (e.g. ETH)
type: string
from_amount_requested:
description: Amount of the asset to trade
type: string
format: decimal
required:
- external_id
- from_asset_code
- to_asset_code
- from_amount_requested
InitiateTradeResponse:
type: object
properties:
id:
description: Trade ID
type: string
format: uuid
required:
- id
InitiateTradeTxnRequest:
type: object
properties:
external_id:
description: Unique ID to ensure idempotency
type: string
from_asset_code:
description: Code of asset to sell
type: string
from_amount:
description: The total `amount` to be sold
type: string
format: decimal
to_asset_code:
description: Code of asset to buy
type: string
quote_id:
nullable: true
description: Optional quote ID, does market order if not provided
type: string
customer_fee:
nullable: true
description: Optional fee to pay treasury in from_asset_code for network fee
type: string
format: decimal
required:
- external_id
- from_asset_code
- from_amount
- to_asset_code
InitiateTradeTxnResponse:
type: object
properties:
id:
description: Trade transaction ID
type: string
format: uuid
required:
- id
InitiateWithdrawRequest:
type: object
properties:
externalId:
type: string
fiatCurrency:
$ref: '#/components/schemas/FiatCurrencyId'
countryCode:
$ref: '#/components/schemas/CountryCode'
assetCode:
type: string
amount:
type: string
paymentInstructionId:
type: string
format: uuid
paymentPurpose:
$ref: '#/components/schemas/PaymentPurpose'
required:
- externalId
- fiatCurrency
- countryCode
- assetCode
- amount
- paymentInstructionId
- paymentPurpose
InitiateWithdrawResponse:
type: object
properties:
id:
description: Id of the withdraw transaction
type: string
format: uuid
required:
- id
ListApprovalRequestsResponse:
type: object
properties:
approval_requests:
type: array
items:
$ref: '#/components/schemas/ApprovalRequest'
required:
- approval_requests
ListAssetRestrictionsResponse:
type: object
properties:
asset_restrictions:
type: array
items:
$ref: '#/components/schemas/AssetRestrictions'
required:
- asset_restrictions
ListBalancesParams:
type: object
properties:
asset_code:
nullable: true
description: Asset code to filter results by
type: string
page:
description: Page number for paginated results
type: integer
page_size:
description: Page size for paginated results
type: integer
required:
- page
- page_size
ListCoreTradesParams:
type: object
properties:
page:
description: Page number for paginated results
type: integer
page_size:
description: Page size for paginated results
type: integer
from_asset_code:
nullable: true
description: Filter by asset code held by user before trade (e.g. BTC)
type: string
to_asset_code:
nullable: true
description: Filter by asset code held by user after trade (e.g. BTC)
type: string
required:
- page
- page_size
ListCurrentTradesParams:
type: object
properties:
last_hours:
nullable: true
description: Limit results to last N hours (e.g. last 24 hours)
type: integer
page:
description: Page number for paginated results
type: integer
page_size:
description: Page size for paginated results
type: integer
required:
- page
- page_size
ListFiatRampTransactionsResponse:
type: object
properties:
transactions:
type: array
items:
$ref: '#/components/schemas/FiatRampTransaction'
required:
- transactions
ListParams:
type: object
properties:
page:
description: Page number for paginated results
type: integer
page_size:
description: Page size for paginated results
type: integer
required:
- page
- page_size
ListTransactionParams:
type: object
properties:
page:
description: Page number for paginated results
type: integer
page_size:
description: Page size for paginated results
type: integer
asset_code:
nullable: true
description: Optional asset code to filter by (e.g. BTC)
type: string
contract_types:
description: Contract types to filter by (defaults to all types if empty)
type: array
items:
$ref: '#/components/schemas/ContractType'
status:
$ref: '#/components/schemas/StatusFilter'
required:
- page
- page_size
- contract_types
ListUserIdentitiesResponse:
type: object
properties:
identities:
description: List of user identities
type: array
items:
$ref: '#/components/schemas/UserIdentity'
required:
- identities
ListWebhookHistoryResponse:
type: object
properties:
webhooks:
type: array
items:
$ref: '#/components/schemas/WebhookDelivery'
required:
- webhooks
ListWebhookSubscriptionsParams:
type: object
properties:
active:
nullable: true
description: Optional filter for active/unactive subscriptions
type: boolean
page:
description: Page number for paginated results
type: integer
page_size:
description: Page size for paginated results
type: integer
required:
- page
- page_size
ListWebhookSubscriptionsResponse:
type: object
properties:
subscriptions:
description: List of webhook subscriptions
type: array
items:
$ref: '#/components/schemas/WebhookSubscription'
required:
- subscriptions
MarketMaker:
type: object
properties:
id:
description: ID of the market maker
type: string
format: uuid
name:
description: Name of the market maker
type: string
verifier:
description: Wallet verifier associated with the market maker
type: string
created:
description: Timestamp when the market maker was created
type: string
format: date-time
required:
- id
- name
- verifier
- created
MintRequest:
type: object
properties:
external_id:
description: Unique ID to ensure idempotency.
type: string
asset_code:
description: Code of asset to transfer.
type: string
amount:
description: Amount to transfer.
type: string
format: decimal
fee_level:
$ref: '#/components/schemas/FeeLevel'
memo:
nullable: true
description: Optional memo to attach to transaction.
type: string
required:
- external_id
- asset_code
- amount
- fee_level
MintResponse:
type: object
properties:
id:
description: Mint transaction ID.
type: string
format: uuid
required:
- id
MobileMoneyDetailsCreateDto:
type: object
properties:
phone:
description: The phone number associated with the mobile money account
type: string
networkSlug:
nullable: true
description: The mobile money network operator slug.
type: string
accountHolderName:
description: The name of the account holder for the mobile money account
type: string
networkProvider:
$ref: '#/components/schemas/MobileMoneyProvider'
required:
- phone
- accountHolderName
MobileMoneyDetailsEntity:
type: object
properties:
accountHolderName:
type: string
phone:
type: string
networkProvider:
$ref: '#/components/schemas/MobileMoneyProvider'
networkSlug:
$ref: '#/components/schemas/MobileMoneyProvider'
required:
- accountHolderName
- phone
MobileMoneyProvider:
type: string
enum:
- AIRTEL
- BKTRX
- CHECKOUT
- CRDTRX
- EXPRESSO
- FLOOZ
- FREE
- HALOPESA
- MOBICASH
- MOOV
- MPESA
- MTN
- MYZAKA
- ORANGE
- TIGO
- TMONEY
- TNM
- VODACOM
- VODAFONE
- WAVE
- ZAMTEL
MonthlyAmounts:
type: string
enum:
- LessThan5K
- From5KTo10K
- From10KTo50K
- GreaterThan50K
NetworkFees:
type: object
properties:
fee_per_byte:
nullable: true
description: for utxo based networks
type: string
format: decimal
gas_price:
nullable: true
description: for evm based networks
type: string
format: decimal
network_fee:
nullable: true
description: fee for non-evm and non-utxo based networks
type: string
format: decimal
base_fee:
nullable: true
description: eth assets
type: string
format: decimal
priority_fee:
nullable: true
description: eth assets
type: string
format: decimal
Occupations:
type: string
enum:
- '132011'
- '272011'
- '152011'
- '291291'
- '519191'
- '113012'
- '112011'
- '413011'
- '172011'
- '131011'
- '194010'
- '191010'
- '172021'
- '452011'
- '532020'
- '493011'
- '532010'
- '512011'
- '533011'
- '452021'
- '392021'
- '339011'
- '392011'
- '171011'
- '173011'
- '119041'
- '254010'
- '271010'
- '192010'
- '272021'
- '192021'
- '291181'
- '492097'
- '493021'
- '493022'
- '493023'
- '492091'
- '396010'
- '333011'
- '513011'
- '395011'
- '353011'
- '433011'
- '433021'
- '172031'
- '191020'
- '194021'
- '472011'
- '433031'
- '472020'
- '273011'
- '274010'
- '434011'
- '132031'
- '493031'
- '131199'
- '513020'
- '131021'
- '517011'
- '292031'
- '435011'
- '472031'
- '472040'
- '412010'
- '472050'
- '351011'
- '172041'
- '519010'
- '194031'
- '192030'
- '111011'
- '211021'
- '399011'
- '291011'
- '172051'
- '131030'
- '537061'
- '212011'
- '193033'
- '292010'
- '272022'
- '499091'
- '271021'
- '499092'
- '432099'
- '113111'
- '131141'
- '131041'
- '151221'
- '113021'
- '172061'
- '151241'
- '519160'
- '151299'
- '151251'
- '151230'
- '151211'
- '492011'
- '191030'
- '474011'
- '472070'
- '472061'
- '119021'
- '499010'
- 5370XX
- '352010'
- '333012'
- '434021'
- '131051'
- '211019'
- '412021'
- '435021'
- '273092'
- '434031'
- '537021'
- '132041'
- '434041'
- '132070'
- '339091'
- '519020'
- '434051'
- '519030'
- '514031'
- '272030'
- '439021'
- 15124X
- '519080'
- '319091'
- '291292'
- '291020'
- '475010'
- '439031'
- '333021'
- '292032'
- 29205X
- '291031'
- '359011'
- '212021'
- '272091'
- '359021'
- '435032'
- '419091'
- '533030'
- '472080'
- '475023'
- '193011'
- '273041'
- '119030'
- '211012'
- '492092'
- '173023'
- '172070'
- '492093'
- 49209X
- '499051'
- '512020'
- '472111'
- '492096'
- '252020'
- '474021'
- '434061'
- 3940XX
- '119161'
- '292042'
- '291214'
- '512031'
- '172199'
- '272099'
- '119070'
- '172081'
- '194040'
- '192041'
- '519194'
- '475022'
- '436011'
- '291128'
- '399031'
- '475032'
- '519041'
- '113013'
- '119013'
- '271022'
- '353023'
- '474031'
- '434071'
- '132051'
- '433099'
- '132061'
- '113031'
- '332020'
- '332011'
- '552010'
- '471011'
- '331011'
- '451011'
- '331021'
- '351012'
- '371011'
- '371012'
- '491011'
- '411012'
- '431011'
- '331012'
- '511011'
- '331099'
- '411011'
- '331091'
- '333031'
- '453031'
- '532031'
- '271023'
- '513091'
- '513092'
- '513093'
- '359099'
- '352021'
- '513099'
- '353041'
- '119051'
- '454011'
- '514020'
- '131131'
- '119171'
- '519051'
- '517021'
- '433041'
- '393010'
- '111021'
- 19204X
- '472121'
- '452041'
- '271024'
- '514033'
- '395012'
- '474041'
- '291299'
- '211022'
- '499021'
- '493040'
- '499098'
- '519198'
- '473010'
- '474051'
- '499031'
- '311121'
- '359031'
- '434081'
- '434161'
- '113121'
- '131070'
- 49904X
- '172110'
- '113051'
- '537051'
- '434199'
- '151212'
- '519061'
- '472130'
- '439041'
- '413021'
- '132053'
- '271025'
- '273091'
- '434111'
- 37201X
- '519071'
- '231020'
- '231012'
- '537062'
- '171012'
- '373011'
- '516011'
- '231011'
- '436012'
- '232099'
- '111031'
- '254022'
- '434121'
- '254031'
- '292061'
- '191099'
- '434131'
- '499094'
- '534010'
- '119081'
- '454020'
- '131081'
- '537063'
- '514041'
- '292035'
- '372012'
- '439051'
- '499071'
- '499043'
- '131111'
- '119199'
- '395092'
- '499095'
- '172121'
- '131161'
- '112021'
- '211013'
- '319011'
- '172131'
- '152021'
- '172141'
- '274099'
- '273099'
- '119111'
- '319092'
- '292072'
- '191040'
- '436013'
- '319094'
- '131121'
- '211023'
- '211014'
- '271026'
- '514050'
- '435041'
- '553010'
- '551010'
- '554010'
- '499044'
- '172151'
- '452090'
- '474090'
- '292090'
- '518090'
- '193090'
- '493090'
- '514060'
- '419010'
- '514070'
- '519195'
- '394031'
- '533099'
- '272041'
- '272042'
- '119121'
- '151244'
- '434141'
- '273023'
- '172161'
- 29203X
- '194051'
- '291151'
- '291161'
- '291171'
- '311131'
- '195010'
- '291122'
- '312010'
- '439199'
- '439061'
- '439071'
- '152031'
- '292081'
- '291041'
- '434151'
- 31113X
- 5120XX
- 21109X
- 27102X
- 17301X
- 2590XX
- 17302X
- 3930XX
- 4750XX
- 1320XX
- 37301X
- '299000'
- 31909X
- 49909X
- 1940XX
- 51403X
- 5371XX
- 1520XX
- 514XXX
- 39509X
- 2912XX
- 51919X
- 5191XX
- 33909X
- 19303X
- 5340XX
- 2530XX
- 51609X
- 5360XX
- 5170XX
- '519111'
- '537064'
- '472140'
- '519120'
- '519196'
- '232011'
- '292043'
- '536021'
- '333041'
- '412022'
- '536061'
- '433051'
- '399099'
- '132052'
- '119179'
- '372021'
- '172171'
- '291051'
- '319095'
- '292052'
- '319097'
- '274021'
- '519151'
- '192099'
- '291123'
- '312020'
- '291071'
- '472151'
- '472161'
- '472152'
- '291081'
- '333050'
- '435051'
- '435052'
- '435053'
- '119131'
- '251000'
- '518010'
- '499060'
- '515111'
- '252010'
- '516021'
- '515113'
- '515112'
- '339021'
- '211092'
- '433061'
- '272012'
- '435061'
- '131082'
- '439081'
- '132020'
- '119141'
- '292053'
- '112030'
- '273031'
- '435031'
- '537070'
- '131023'
- '113061'
- '291124'
- '492020'
- '292034'
- '291224'
- '474061'
- '534031'
- '419020'
- '434171'
- '399032'
- '291125'
- '537081'
- '291141'
- '211015'
- '472171'
- '212099'
- '434181'
- '399041'
- '291126'
- '412031'
- '499096'
- '472181'
- '475071'
- '535011'
- '419099'
- '419031'
- '112022'
- '413091'
- '414010'
- '517041'
- '533051'
- '339094'
- '193034'
- '252030'
- '436014'
- '413031'
- '492098'
- '339030'
- '474071'
- '516031'
- '472211'
- '535020'
- '535031'
- '435071'
- '516040'
- '533053'
- '395094'
- '493050'
- '119151'
- '211093'
- '194061'
- '211029'
- '193041'
- '151252'
- '151253'
- '472231'
- '252050'
- '291127'
- '518021'
- '439111'
- '152041'
- '537065'
- '472221'
- '512041'
- '211011'
- '391000'
- '531000'
- '291240'
- '292055'
- '193022'
- '173031'
- '171020'
- '432011'
- '516050'
- '132081'
- '132082'
- '533054'
- '259040'
- '273042'
- '499052'
- '419041'
- '432021'
- '274030'
- '433071'
- '516060'
- '291129'
- '519197'
- '232093'
- '514111'
- '397010'
- '113131'
- '131151'
- '533052'
- '536051'
- '339093'
- '536030'
- '113071'
- '413041'
- '373013'
- '253041'
- '272023'
- '475040'
- '999999'
- '516093'
- '193051'
- '393031'
- '291131'
- '319096'
- '292056'
- '353031'
- '518031'
- '151255'
- '151254'
- '435111'
- '514120'
- '131022'
- '499081'
- '517042'
- '439022'
- '273043'
OnchainTransaction:
type: object
properties:
to:
$ref: '#/components/schemas/Address'
from:
$ref: '#/components/schemas/Address'
asset_code:
description: Asset code (e.g. BTC)
type: string
amount:
description: Amount of the asset sent or received
type: string
format: decimal
fee_asset_code:
description: Asset code used to pay transaction fees (e.g. BTC)
type: string
network_fee:
description: Amount of the transaction fees
type: string
format: decimal
fee_level:
$ref: '#/components/schemas/FeeLevel'
status:
$ref: '#/components/schemas/OnchainTransactionStatus'
substatus:
nullable: true
description: Secondary status on the transaction
type: string
tx_hash:
nullable: true
description: Transaction hash of the onchain transaction
type: string
created:
description: Timestamp when the transaction was created
type: string
format: date-time
required:
- asset_code
- amount
- fee_asset_code
- network_fee
- status
- created
OnchainTransactionStatus:
type: string
enum:
- Pending
- Confirmed
- Failed
OptionsRequest:
type: object
properties:
countryCode:
$ref: '#/components/schemas/CountryCode'
required:
- countryCode
OptionsResponse:
type: object
properties:
options:
description: List of payment instructions
type: array
items:
$ref: '#/components/schemas/RampOptionEntity'
required:
- options
Payload:
oneOf:
- type: object
properties:
ApprovalRequest:
type: object
properties:
uetr:
description: The unique identifier for the approval request
type: string
format: uuid
idempotency_key:
description: The idempotency key associated with the approval request
type: string
format: uuid
required:
- uetr
- idempotency_key
required:
- ApprovalRequest
- type: object
properties:
ContractTransaction:
type: object
properties:
id:
description: Id of contract transaction
type: string
format: uuid
external_id:
nullable: true
description: Idemopotency key used for the transaction
type: string
external_transactions:
description: List of external transactions
type: array
items:
$ref: '#/components/schemas/ExternalTransaction'
digital_twin_transactions:
description: List of digital twin transactions
type: array
items:
$ref: '#/components/schemas/DigitalTwinTransaction'
digital_twin_summary:
description: Summary of digital twin asset changes per user
type: object
additionalProperties:
type: object
additionalProperties:
type: string
format: decimal
contract_type:
$ref: '#/components/schemas/ContractType'
status:
description: Status of the contract transaction
type: string
memo:
nullable: true
description: Optional memo attached to the contract
type: string
created:
description: Timestamp when the transaction was created
type: string
format: date-time
required:
- id
- external_transactions
- digital_twin_transactions
- digital_twin_summary
- contract_type
- status
- created
required:
- ContractTransaction
PaymentInstructionCreateDto:
type: object
properties:
country:
$ref: '#/components/schemas/CountryCode'
currency:
$ref: '#/components/schemas/FiatCurrencyId'
name:
description: A unique identifier for a payment instruction, allowing to distinguish it from other accounts.
type: string
paymentMethod:
$ref: '#/components/schemas/PaymentMethod'
details:
$ref: '#/components/schemas/PaymentInstructionCreateDtoDetails'
required:
- country
- currency
- name
- paymentMethod
- details
PaymentInstructionCreateDtoDetails:
oneOf:
- type: object
properties:
bankName:
nullable: true
description: The name of the bank, if applicable
type: string
accountHolderName:
description: The name of the account holder for the US bank account
type: string
bankAccountNumber:
description: The bank account number for the US account
type: string
bankRoutingNumber:
description: The bank routing number (ABA) for the US account
type: string
bankAccountType:
$ref: '#/components/schemas/BankAccountType'
address:
$ref: '#/components/schemas/PostalAddressCreateDto'
required:
- accountHolderName
- bankAccountNumber
- bankRoutingNumber
- bankAccountType
- address
- type: object
properties:
bankCode:
nullable: true
description: The bank code for the account, such as a routing number or sort code.
type: string
bankSlug:
nullable: true
description: The bank code for the account, such as a routing number or sort code
type: string
bankAccountNumber:
description: The bank account number
type: string
address:
$ref: '#/components/schemas/PostalAddressCreateDto'
bankName:
nullable: true
description: The name of the bank.
type: string
phone:
nullable: true
description: The phone number associated with the bank account.
type: string
taxId:
nullable: true
description: The tax identification number associated with the account.
type: string
accountHolderName:
nullable: true
description: The name of the account holder. Required for Colombia. Learn more at [Payment Instructions Guide](https://docs.buildborderless.com/docs/latam-payment-instructions).
type: string
bankAccountType:
$ref: '#/components/schemas/BankAccountType'
bankAccountNumberType:
$ref: '#/components/schemas/BankAccountNumberType'
required:
- bankAccountNumber
- address
- type: object
properties:
identifierType:
$ref: '#/components/schemas/PaymentInstructionIdentifierType'
identifierValue:
description: The value of the identifier, such as a PIX key or similar
type: string
phone:
nullable: true
description: The phone number associated with the identifier.
type: string
taxId:
nullable: true
description: The tax identification number associated with the identifier.
type: string
address:
$ref: '#/components/schemas/PostalAddressCreateDto'
required:
- identifierType
- identifierValue
- address
- type: object
properties:
bankName:
nullable: true
description: The name of the bank.
type: string
accountHolderName:
description: The name of the account holder for the SEPA account.
type: string
bankAccountNumber:
description: The IBAN (International Bank Account Number) for the SEPA account.
type: string
swiftOrBicNumber:
description: The SWIFT or BIC code of the bank.
type: string
accountOwnerType:
$ref: '#/components/schemas/BankAccountOwnerType'
firstName:
nullable: true
description: The first name of the account holder, required if accountOwnerType is Personal
type: string
lastName:
nullable: true
description: The last name of the account holder, required if accountOwnerType is Personal
type: string
businessName:
nullable: true
description: The business name, required if accountOwnerType is Business
type: string
address:
$ref: '#/components/schemas/PostalAddressCreateDto'
required:
- accountHolderName
- bankAccountNumber
- swiftOrBicNumber
- accountOwnerType
- address
- type: object
properties:
phone:
description: The phone number associated with the mobile money account
type: string
networkSlug:
nullable: true
description: The mobile money network operator slug.
type: string
accountHolderName:
description: The name of the account holder for the mobile money account
type: string
networkProvider:
$ref: '#/components/schemas/MobileMoneyProvider'
required:
- phone
- accountHolderName
PaymentInstructionEntity:
type: object
properties:
id:
type: string
name:
type: string
paymentMethod:
$ref: '#/components/schemas/PaymentMethod'
currency:
type: string
country:
$ref: '#/components/schemas/CountryCode'
deleted:
type: boolean
details:
$ref: '#/components/schemas/PaymentInstructionEntityDetails'
required:
- id
- name
- paymentMethod
- currency
- country
- deleted
- details
PaymentInstructionEntityDetails:
oneOf:
- type: object
properties:
bankName:
nullable: true
type: string
bankSlug:
nullable: true
type: string
bankAccountNumberLast4:
type: string
bankRoutingNumber:
nullable: true
type: string
bankCode:
nullable: true
type: string
phone:
nullable: true
type: string
taxId:
nullable: true
type: string
accountHolderName:
nullable: true
type: string
bankAccountType:
$ref: '#/components/schemas/BankAccountType'
address:
$ref: '#/components/schemas/PostalAddressEntity'
required:
- bankAccountNumberLast4
- type: object
properties:
identifierType:
$ref: '#/components/schemas/PaymentInstructionIdentifierType'
identifierValue:
type: string
address:
$ref: '#/components/schemas/PostalAddressEntity'
required:
- identifierType
- identifierValue
- address
- type: object
properties:
id:
nullable: true
type: string
- type: object
properties:
bankName:
type: string
bankAccountNumberLast4:
type: string
accountHolderName:
type: string
swiftOrBicNumber:
type: string
accountOwnerType:
$ref: '#/components/schemas/BankAccountOwnerType'
firstName:
nullable: true
type: string
lastName:
nullable: true
type: string
businessName:
nullable: true
type: string
address:
$ref: '#/components/schemas/PostalAddressEntity'
required:
- bankName
- bankAccountNumberLast4
- accountHolderName
- swiftOrBicNumber
- accountOwnerType
- type: object
properties:
bankName:
type: string
bankAccountNumberLast4:
type: string
swiftOrBicNumber:
type: string
accountOwnerType:
$ref: '#/components/schemas/BankAccountOwnerType'
accountHolderName:
type: string
businessDescription:
type: string
businessOperation:
$ref: '#/components/schemas/BusinessOperation'
purposeOfFunds:
$ref: '#/components/schemas/BusinessPurposeOfFunds'
businessName:
type: string
address:
$ref: '#/components/schemas/PostalAddressEntity'
required:
- bankName
- bankAccountNumberLast4
- swiftOrBicNumber
- accountOwnerType
- accountHolderName
- businessDescription
- businessOperation
- purposeOfFunds
- businessName
- type: object
properties:
accountHolderName:
type: string
phone:
type: string
networkProvider:
$ref: '#/components/schemas/MobileMoneyProvider'
networkSlug:
$ref: '#/components/schemas/MobileMoneyProvider'
required:
- accountHolderName
- phone
PaymentInstructionIdentifierType:
type: string
enum:
- PhoneNumber
- Email
- TaxID
- UUID
PaymentMethod:
type: string
enum:
- ACH
- Wire
- Sepa
- Swift
- Card
- MobileMoney
- PIX
- PSE
- SPEI
- COELSA
- SPAV
- CCE
- NIP
- GhIPSS
- BankTransfer
- EFT
PaymentPurpose:
type: string
enum:
- salary payment
- personal remittance
- rent payment
- property purchase
- owned account abroad
- advertising expenses
- advisory fees
- business insurance
- construction
- delivery fees
- education
- exports
- donation
- hotel
- loan payment
- maintenance expenses
- medical expense
- office expenses
- royalty fees
- service charge
- shares investment
- tax payment
- transportation fees
- travel
- utility bills
- other
PersonalAccountPurpose:
type: string
enum:
- CharitableDonations
- EcommerceRetailPayments
- InvestmentPurposes
- OperatingACompany
- Other
- PaymentsToFriendsOrFamilyAbroad
- PersonalOrLivingExpenses
- ProtectWealth
- PurchaseGoodsAndServices
- ReceivePaymentForFreelancing
- ReceiveSalary
PersonalSourceOfFunds:
type: string
enum:
- CompanyFunds
- EcommerceReseller
- GamblingProceeds
- Gifts
- GovernmentBenefits
- Inheritance
- InvestmentsLoans
- PensionRetirement
- Salary
- SaleOfAssetsRealEstate
- Savings
- SomeoneElsesFunds
PostalAddressCreateDto:
type: object
properties:
street1:
description: The primary street address
type: string
street2:
nullable: true
description: Additional street address information, if applicable
type: string
city:
description: The city of the address
type: string
state:
nullable: true
description: The state/province/region/county code in ISO-3166-2 format. Required if country has subdivision. See [ISO-3166-2 documentation](https://www.iso.org/iso-3166-country-codes.html).
type: string
country:
$ref: '#/components/schemas/CountryCode'
postalCode:
nullable: true
description: The postal code for the address, validated based on the country
type: string
required:
- street1
- city
- country
PostalAddressEntity:
type: object
properties:
id:
type: string
street1:
type: string
street2:
nullable: true
type: string
city:
type: string
state:
nullable: true
type: string
country:
$ref: '#/components/schemas/CountryCode'
postalCode:
type: string
required:
- id
- street1
- city
- country
- postalCode
RampOptionEntity:
type: object
properties:
id:
description: Unique identifier for on/off ramp option
type: string
country:
$ref: '#/components/schemas/CountryCode'
method:
$ref: '#/components/schemas/PaymentMethod'
fiat:
$ref: '#/components/schemas/FiatCurrencyId'
asset:
description: Asset code, e.g. BTC
type: string
required:
- id
- country
- method
- fiat
- asset
RebalanceRequest:
type: object
properties:
external_id:
description: Unique ID to ensure idempotency.
type: string
asset_code:
description: Asset code (e.g. BTC)
type: string
source_vendor:
$ref: '#/components/schemas/CustodyVendor'
source_vault_id:
description: Vault ID from which to move assets
type: string
destination:
$ref: '#/components/schemas/Address'
amount:
description: Amount to move
type: string
fee_level:
$ref: '#/components/schemas/FeeLevel'
memo:
description: Memo for the transaction
type: string
required:
- external_id
- asset_code
- source_vendor
- source_vault_id
- destination
- amount
- fee_level
- memo
RebalanceResponse:
type: object
properties:
vendor_txn_id:
description: Vendor transaction ID
type: string
required:
- vendor_txn_id
RegisterTreasuryUserRequest:
type: object
properties:
vault_id:
description: Vault ID of the custody vendor to associate with the user
type: string
vendor:
$ref: '#/components/schemas/CustodyVendor'
required:
- vault_id
RegisterUserRequest:
description: Register new user using given user_id.
type: object
properties:
id:
description: ID of the user
type: string
format: uuid
username:
nullable: true
description: Name of the user
type: string
required:
- id
RegisterUserResponse:
description: Returns verifier token after successful user registration.
type: object
properties:
verifier:
description: User's generated wallet verifier
type: string
required:
- verifier
ResendTxnWebhooksRequest:
type: object
properties:
webhook_id:
description: The webhook ID
type: string
vendor_txn_id:
description: The vendor transaction ID
type: string
format: uuid
required:
- webhook_id
- vendor_txn_id
ResendWebhooksRequest:
type: object
properties:
webhook_id:
description: The webhook ID
type: string
required:
- webhook_id
RetryFailedTradeFillRequest:
type: object
properties:
trade_fill_id:
description: ID of the trade fill to retry
type: string
format: uuid
required:
- trade_fill_id
RetryFailedTradeFillResponse:
type: object
properties:
trade_fill_id:
description: ID of the new trade fill
type: string
format: uuid
required:
- trade_fill_id
RetryFailedTradeRefundRequest:
type: object
properties:
trade_id:
description: ID of the failed trade to retry
type: string
format: uuid
required:
- trade_id
RetryFailedTradeRefundResponse:
type: object
properties:
trade_funding_id:
description: ID of the newly created trade funding
type: string
format: uuid
required:
- trade_funding_id
Role:
type: string
enum:
- admin
- checker
- maker
SellRequest:
type: object
properties:
external_id:
type: string
base_asset_code:
type: string
token_asset_code:
type: string
amount:
type: string
required:
- external_id
- base_asset_code
- token_asset_code
- amount
SellResponse:
type: object
properties:
id:
type: string
format: uuid
required:
- id
SepaDetailsCreateDto:
type: object
properties:
bankName:
nullable: true
description: The name of the bank.
type: string
accountHolderName:
description: The name of the account holder for the SEPA account.
type: string
bankAccountNumber:
description: The IBAN (International Bank Account Number) for the SEPA account.
type: string
swiftOrBicNumber:
description: The SWIFT or BIC code of the bank.
type: string
accountOwnerType:
$ref: '#/components/schemas/BankAccountOwnerType'
firstName:
nullable: true
description: The first name of the account holder, required if accountOwnerType is Personal
type: string
lastName:
nullable: true
description: The last name of the account holder, required if accountOwnerType is Personal
type: string
businessName:
nullable: true
description: The business name, required if accountOwnerType is Business
type: string
address:
$ref: '#/components/schemas/PostalAddressCreateDto'
required:
- accountHolderName
- bankAccountNumber
- swiftOrBicNumber
- accountOwnerType
- address
SepaDetailsEntity:
type: object
properties:
bankName:
type: string
bankAccountNumberLast4:
type: string
accountHolderName:
type: string
swiftOrBicNumber:
type: string
accountOwnerType:
$ref: '#/components/schemas/BankAccountOwnerType'
firstName:
nullable: true
type: string
lastName:
nullable: true
type: string
businessName:
nullable: true
type: string
address:
$ref: '#/components/schemas/PostalAddressEntity'
required:
- bankName
- bankAccountNumberLast4
- accountHolderName
- swiftOrBicNumber
- accountOwnerType
ServiceProviderStakingData:
type: object
properties:
provider:
type: string
enum:
- Ethereum
data:
type: array
items:
type: object
properties:
id:
description: Unique stake identifier.
type: string
amount:
description: Amount of ETH (denominated in Gwei).
type: string
validator_public_key:
description: A BLS public Key.
type: string
withdrawal_credentials:
description: |-
Hexadecimal encoded [withdrawal credentials](https://github.com/ethereum/consensus-specs/blob/master/specs/phase0/validator.md#withdrawal-credentials)
which can be either a BLS public key or an Ethereum account address. This parameter currently accepts ETH1 and BLS withdrawal credentials, but it is
considered deprecated after the Capella/Shanghai fork. All users are now advised to use an ETH1 withdrawal address, specified through the
`withdrawal_address` parameter as this is required to enable the ongoing accrual of rewards.
For more information regarding creating withdrawal credentials, please see the official
[Ethereum Launchpad FAQ](https://launchpad.ethereum.org/en/faq#withdrawal-credentials).
type: string
fee_recipient:
description: An Ethereum address to receive transaction fees from published blocks. 20-bytes, hex encoded with 0x prefix, case insensitive.
type: string
required:
- id
- amount
- validator_public_key
- withdrawal_credentials
- fee_recipient
required:
- provider
- data
ServiceProviderUnstakingData:
type: object
properties:
provider:
type: string
enum:
- Ethereum
data:
type: object
properties:
validator_public_key:
description: A BLS public Key.
type: string
required:
- validator_public_key
required:
- provider
- data
SetAssetRestrictionsRequest:
type: object
properties:
asset_code:
description: Asset code the restrictions apply to
type: string
role:
description: Role the restrictions apply to
type: string
max_maker_amount:
nullable: true
description: Maximum maker amount to set for the role
type: string
required:
- asset_code
- role
SetAutomationRequest:
type: object
properties:
name:
description: User-defined name
type: string
trigger:
$ref: '#/components/schemas/Trigger'
condition:
$ref: '#/components/schemas/Condition'
action:
$ref: '#/components/schemas/Action'
status:
$ref: '#/components/schemas/AutomationStatus'
first_run:
nullable: true
description: Optional override for first run time in ISO3339 format
type: string
format: date-time
required:
- name
- trigger
- condition
- action
- status
SetAutomationResponse:
type: object
properties:
id:
description: Id of the automation
type: string
format: uuid
required:
- id
SetAutomationStatusRequest:
type: object
properties:
enable:
description: Whether to enable (true) or disable (false) the automation
type: boolean
required:
- enable
SetAutomationStatusResponse:
type: object
properties:
enabled:
description: Repeats the enabled status set in the request
type: boolean
required:
- enabled
SetFiatProviderRequest:
description: Set Fiat Provider configuration.
type: object
properties:
customer:
description: Customer ID (i.e. cus_*)
type: string
payin_payment_method:
description: Payment method (i.e. pm_*)
type: string
payin_payment_method_type:
description: Payment method type (i.e. us_bank_account, debit, etc.)
type: string
financial_connections_account:
description: Financial connections account (i.e. fca_*)
type: string
financial_account:
description: Financial account (i.e. fa_*)
type: string
payout_account:
description: Payout account (i.e. acct_*)
type: string
payout_method:
description: Payout method (i.e. usba_*)
type: string
required:
- customer
- payin_payment_method
- payin_payment_method_type
- financial_connections_account
- financial_account
- payout_account
- payout_method
SetFiatProviderResponse:
description: Response after setting Fiat Provider configuration.
type: object
properties:
id:
description: ID
type: string
format: uuid
required:
- id
SetIdentityRequest:
type: object
properties:
firstName:
description: The first name
type: string
lastName:
description: The last name
type: string
secondLastName:
nullable: true
description: The second last name
type: string
middleName:
nullable: true
description: The middle name
type: string
taxId:
nullable: true
description: The tax identification number
type: string
dateOfBirth:
description: The date of birth in format yyyy-mm-dd
type: string
email:
nullable: true
description: The email address
type: string
phone:
nullable: true
description: The phone number
type: string
activity:
nullable: true
description: The activity or occupation
type: string
sex:
$ref: '#/components/schemas/Sex'
occupationCode:
$ref: '#/components/schemas/Occupations'
employmentStatus:
$ref: '#/components/schemas/EmploymentStatus'
sourceOfFunds:
$ref: '#/components/schemas/PersonalSourceOfFunds'
accountPurpose:
$ref: '#/components/schemas/PersonalAccountPurpose'
accountPurposeOther:
nullable: true
description: Other account purpose (required if accountPurpose is 'Other')
type: string
monthlyAmounts:
$ref: '#/components/schemas/MonthlyAmounts'
actingAsIntermediary:
nullable: true
description: Whether the person is acting as an intermediary for another party
type: boolean
address:
$ref: '#/components/schemas/PostalAddressCreateDto'
documents:
description: List of documents to attach
type: array
items:
$ref: '#/components/schemas/IdentityDocumentCreateDto'
required:
- firstName
- lastName
- dateOfBirth
- address
- documents
SetIdentityResponse:
type: object
properties:
id:
description: Id of the automation
type: string
format: uuid
tos_link:
description: Link to the Terms of Service acceptance form
type: string
tos_accepted:
description: Indicate if the Terms of Service has been accepted
type: boolean
required:
- id
- tos_link
- tos_accepted
Sex:
type: string
enum:
- Male
- Female
SingleTradeFillRequest:
type: object
properties:
market_maker_id:
description: ID of the market maker
type: string
format: uuid
from_amount:
description: Amount of the asset being sold by the user
type: string
format: decimal
to_amount:
description: Amount of the asset being bought by the user
type: string
format: decimal
fee_asset_code:
description: Asset code for the fee (e.g. BTC)
type: string
fee_amount:
description: Amount of the fee
type: string
format: decimal
auto_close:
description: |-
Whether or not to close the trade when the fill is submitted.
If this is false, the trade stays open for more fills to be added.
type: boolean
required:
- market_maker_id
- from_amount
- to_amount
- fee_asset_code
- fee_amount
- auto_close
SingleTradeFillResponse:
type: object
properties:
id:
description: Trade Fill ID
type: string
format: uuid
required:
- id
StakeRequest:
type: object
properties:
vault_id:
description: Vault ID for the custody vendor used to provide staking assets.
type: string
asset_code:
description: Asset code for the staking asset.
type: string
address:
description: Address that will receive unstaked assets and staking rewards.
type: string
amount:
description: Amount to stake (denominated in ETH).
type: string
required:
- vault_id
- asset_code
- address
- amount
StakeResponse:
type: object
properties:
vendor_txn_id:
description: Transaction ID from the custody vendor.
type: string
service_provider_staking_data:
$ref: '#/components/schemas/ServiceProviderStakingData'
required:
- vendor_txn_id
- service_provider_staking_data
StatusFilter:
type: string
enum:
- Initiated
- Failure
- Success
SwiftDetailsEntity:
type: object
properties:
bankName:
type: string
bankAccountNumberLast4:
type: string
swiftOrBicNumber:
type: string
accountOwnerType:
$ref: '#/components/schemas/BankAccountOwnerType'
accountHolderName:
type: string
businessDescription:
type: string
businessOperation:
$ref: '#/components/schemas/BusinessOperation'
purposeOfFunds:
$ref: '#/components/schemas/BusinessPurposeOfFunds'
businessName:
type: string
address:
$ref: '#/components/schemas/PostalAddressEntity'
required:
- bankName
- bankAccountNumberLast4
- swiftOrBicNumber
- accountOwnerType
- accountHolderName
- businessDescription
- businessOperation
- purposeOfFunds
- businessName
Trade:
type: object
properties:
id:
description: ID of the trade
type: string
format: uuid
user_id:
description: ID of the user who is making the trade
type: string
format: uuid
from_asset_code:
description: Asset code the user has before the transaction is initiated
type: string
from_amount_requested:
description: Amount of the from_asset_code being traded
type: string
to_asset_code:
description: Asset code the user has after the transaction is completed
type: string
tr_status:
$ref: '#/components/schemas/TradeStatus'
created:
description: Timestamp when the trade was created
type: string
format: date-time
updated:
description: Timestamp when the trade was last updated
type: string
format: date-time
filled:
description: Fills associated with the trade
type: array
items:
$ref: '#/components/schemas/TradeFill'
refund:
$ref: '#/components/schemas/TradeRefund'
required:
- id
- user_id
- from_asset_code
- from_amount_requested
- to_asset_code
- tr_status
- created
- updated
- filled
TradeFill:
type: object
properties:
fill_id:
description: ID of the trade fill
type: string
format: uuid
market_maker_id:
description: ID of the market maker associated with the fill
type: string
format: uuid
from_amount:
description: Amount of the from_asset_code traded
type: string
format: decimal
to_amount:
description: Amount of the to_asset_code traded
type: string
format: decimal
fee_asset_code:
description: Asset code of the transaction fee
type: string
fee_amount:
description: Amount of the transaction fee
type: string
format: decimal
fill_status:
$ref: '#/components/schemas/CoreTxnStatus'
created:
description: Timestamp when the fill was created
type: string
format: date-time
updated:
description: Timestamp when the fill was last updated
type: string
format: date-time
required:
- fill_id
- market_maker_id
- from_amount
- to_amount
- fee_asset_code
- fee_amount
- fill_status
- created
- updated
TradeRefund:
type: object
properties:
funding_id:
description: ID of the refund
type: string
format: uuid
amount:
description: Amount refunded
type: string
format: decimal
funding_status:
$ref: '#/components/schemas/CoreTxnStatus'
created:
description: Timestamp when the refund was created
type: string
format: date-time
updated:
description: Timestamp when the refund was last updated
type: string
format: date-time
required:
- funding_id
- amount
- funding_status
- created
- updated
TradeStatus:
type: string
enum:
- PendingFunding
- Funded
- PartiallyFilled
- Filled
- Cancelled
- Refunded
- Failed
TransactionResponse:
type: object
properties:
success:
description: Whether the resend was successful
type: boolean
required:
- success
Trigger:
oneOf:
- type: object
properties:
cron_expression:
type: string
type:
type: string
enum:
- time_crontab
required:
- cron_expression
- type
- type: object
properties:
user_id:
type: string
format: uuid
asset_code:
type: string
type:
type: string
enum:
- user_deposit
required:
- user_id
- asset_code
- type
TxFailuresResponse:
type: object
properties:
messages_count:
description: Number of successfully resent messages
type: integer
required:
- messages_count
UnstakeRequest:
type: object
properties:
asset_code:
description: Asset code for the staking asset.
type: string
service_provider_unstaking_data:
$ref: '#/components/schemas/ServiceProviderUnstakingData'
required:
- asset_code
- service_provider_unstaking_data
UpdateDigitalTwinBalanceRequest:
oneOf:
- type: object
properties:
to:
description: User ID of the wallet to issue funds to
type: string
format: uuid
amount:
description: Amount of funds to issue
type: string
format: decimal
asset_code:
description: Asset code of the funds to issue (e.g. BTC)
type: string
memo:
description: Memo for the issuance
type: string
action:
type: string
enum:
- issue
required:
- to
- amount
- asset_code
- memo
- action
- type: object
properties:
from:
description: User ID of the wallet to redeem funds from
type: string
format: uuid
amount:
description: Amount of funds to redeem
type: string
format: decimal
asset_code:
description: Asset code of the funds to redeem (e.g. BTC)
type: string
memo:
description: Memo for the redemption
type: string
action:
type: string
enum:
- redeem
required:
- from
- amount
- asset_code
- memo
- action
- type: object
properties:
from:
description: User ID of the wallet to transfer funds from
type: string
format: uuid
to:
description: User ID of the wallet to transfer funds to
type: string
format: uuid
amount:
description: Amount of funds to transfer
type: string
format: decimal
asset_code:
description: Asset code of the funds to transfer (e.g. BTC)
type: string
memo:
description: Memo for the transfer
type: string
action:
type: string
enum:
- transfer
required:
- from
- to
- amount
- asset_code
- memo
- action
UpdateDigitalTwinBalanceResponse:
type: object
properties:
id:
description: ID of the Knova core transaction
type: string
format: uuid
required:
- id
UpdateWebhookSubscriptionRequest:
type: object
properties:
id:
description: ID of the webhook subscription to update
type: string
format: uuid
url:
nullable: true
description: URL where to send webhook notifications
type: string
active:
nullable: true
description: Indicate if is active (notifications get sent to URL)
type: boolean
required:
- id
UsDetailsCreateDto:
type: object
properties:
bankName:
nullable: true
description: The name of the bank, if applicable
type: string
accountHolderName:
description: The name of the account holder for the US bank account
type: string
bankAccountNumber:
description: The bank account number for the US account
type: string
bankRoutingNumber:
description: The bank routing number (ABA) for the US account
type: string
bankAccountType:
$ref: '#/components/schemas/BankAccountType'
address:
$ref: '#/components/schemas/PostalAddressCreateDto'
required:
- accountHolderName
- bankAccountNumber
- bankRoutingNumber
- bankAccountType
- address
UsdRate:
type: object
properties:
asset_code:
description: Asset code (e.g. BTC)
type: string
usd_rate:
description: Exchange rate of asset relative to USD
type: string
required:
- asset_code
- usd_rate
User:
type: object
properties:
id:
description: ID of the user
type: string
format: uuid
verifier:
description: Wallet verifier of the user
type: string
required:
- id
- verifier
UserAddress:
type: object
properties:
asset_code:
description: Asset code associated with this address (e.g. BTC)
type: string
address:
description: Blockchain address
type: string
tag_memo:
nullable: true
description: Optional tag or memo for the address
type: string
vault_id:
description: ID of the vault this address belongs to
type: string
vendor:
$ref: '#/components/schemas/CustodyVendor'
created:
description: Time the address was created
type: string
format: date-time
required:
- asset_code
- address
- vault_id
- vendor
- created
UserAddressBalance:
type: object
properties:
vault_id:
description: ID of vault in external custody system
type: string
vault_name:
description: Name of the vault in external custody system
type: string
vendor:
$ref: '#/components/schemas/CustodyVendor'
address:
description: Address of the vault
type: string
asset_code:
description: Asset code (e.g. BTC)
type: string
core_amount:
description: Amount of asset held in Knova core
type: string
format: decimal
external_custody_amount:
description: Amount of asset held in external custody
type: string
format: decimal
required:
- vault_id
- vault_name
- vendor
- address
- asset_code
- core_amount
- external_custody_amount
UserAssetBalance:
type: object
properties:
id:
description: User ID
type: string
format: uuid
verifier:
description: User's wallet verifier
type: string
username:
description: Name of this user
type: string
asset_code:
description: Asset code (e.g. BTC)
type: string
amount:
description: Amount of this asset owned by this user
type: string
format: decimal
required:
- id
- verifier
- username
- asset_code
- amount
UserAssetVendorCode:
description: Shows whether user has a matching address for the asset code and vendor.
type: object
properties:
user_id:
description: ID of the user that owns this asset code
type: string
format: uuid
asset_code:
description: Asset code (e.g. BTC)
type: string
vendor_name:
$ref: '#/components/schemas/Vendor'
has_address:
description: '''true'' if the user has an address for this vendor asset code'
type: boolean
required:
- user_id
- asset_code
- vendor_name
- has_address
UserIdentity:
type: object
properties:
user_id:
description: Id of the user
type: string
format: uuid
username:
description: Username of the user
type: string
identity:
$ref: '#/components/schemas/Identity'
required:
- user_id
- username
- identity
UsernameAddress:
type: object
properties:
user_id:
description: ID of the user associated with this address
type: string
format: uuid
username:
description: Username of the user associated with this address
type: string
asset_code:
description: Asset code associated with this address (e.g. BTC)
type: string
address:
description: Blockchain address
type: string
tag_memo:
nullable: true
description: Optional tag or memo for the address
type: string
vault_id:
description: ID of the vault this address belongs to
type: string
vendor:
$ref: '#/components/schemas/CustodyVendor'
created:
description: Time the address was created
type: string
format: date-time
required:
- user_id
- username
- asset_code
- address
- vault_id
- vendor
- created
Vendor:
type: string
enum:
- Fireblocks
- Blockdaemon
- Borderless
- Stripe
VendorAssetBalanceParams:
type: object
properties:
vendors:
description: Optional list of vendors to filter by
type: array
items:
$ref: '#/components/schemas/CustodyVendor'
required:
- vendors
WebhookDelivery:
type: object
properties:
notification:
$ref: '#/components/schemas/WebhookNotification'
delivery_status:
$ref: '#/components/schemas/WebhookDeliveryStatus'
target_url:
description: The URL where the notification was sent
type: string
attempted:
description: The timestamp when the delivery was last attempted
type: string
format: date-time
next_attempt:
nullable: true
description: The timestamp when the delivery will be attempted again
type: string
format: date-time
attempt_count:
description: The number of times the delivery was attempted
type: integer
required:
- notification
- delivery_status
- target_url
- attempted
- attempt_count
WebhookDeliveryStatus:
type: string
enum:
- Pending
- Delivered
- Failed
WebhookNotification:
type: object
properties:
id:
description: ID for this webhook event
type: string
event_type:
$ref: '#/components/schemas/EventType'
payload:
$ref: '#/components/schemas/Payload'
created:
description: Timestamp of when the event was created
type: string
format: date-time
required:
- id
- event_type
- payload
- created
WebhookSubscription:
type: object
properties:
id:
type: string
format: uuid
url:
type: string
active:
type: boolean
created:
type: string
format: date-time
required:
- id
- url
- active
- created