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.21.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"
}
}
}
},
"400": {
"description": "The request body could not be parsed as JSON."
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"409": {
"description": "user is archived"
},
"500": {
"description": "Possible reasons:\n- failed to create knova wallet\n- failed to get user from database\n- failed to get wallet verifier\n- failed to save user in database"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/users/{id}": {
"get": {
"tags": [
"Users"
],
"summary": "Get User by ID",
"description": "Get a user by id.",
"operationId": "get_user_by_id",
"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/User"
}
}
}
},
"400": {
"description": "A path parameter could not be parsed into its expected type."
},
"401": {
"description": "Not authenticated"
},
"404": {
"description": "Not found"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
},
"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": "A path parameter could not be parsed into its expected type."
},
"409": {
"description": "user cannot be archived while having asset balances"
},
"500": {
"description": "Possible reasons:\n- could not begin transactional query\n- failed to archive user\n- failed to commit database transaction\n- failed to get asset balances\n- invalid user verifier"
},
"401": {
"description": "Not authenticated"
},
"404": {
"description": "Not found"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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",
"required": true,
"schema": {
"description": "Page number for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
},
{
"name": "page_size",
"required": true,
"schema": {
"description": "Page size for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/UserAddress"
}
}
}
}
},
"400": {
"description": "A path parameter could not be parsed into its expected type.\n\nThe query string is missing a required parameter, or a parameter could not be parsed into its expected type."
},
"500": {
"description": "failed to get address list"
},
"401": {
"description": "Not authenticated"
},
"404": {
"description": "Not found"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
},
"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"
}
}
}
},
"400": {
"description": "A path parameter could not be parsed into its expected type."
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"401": {
"description": "Not authenticated"
},
"404": {
"description": "Not found"
},
"409": {
"description": "user is archived"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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"
}
}
}
}
},
"400": {
"description": "A path parameter could not be parsed into its expected type."
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"401": {
"description": "Not authenticated"
},
"404": {
"description": "Not found"
},
"409": {
"description": "user is archived"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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"
}
}
}
},
"400": {
"description": "A path parameter could not be parsed into its expected type."
},
"500": {
"description": "failed to get user from database"
},
"404": {
"description": "user not found"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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"
}
}
}
},
"400": {
"description": "A path parameter could not be parsed into its expected type."
},
"500": {
"description": "failed to get asset balance"
},
"404": {
"description": "unknown user"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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": {
"description": "Asset code to filter results by",
"type": "string"
},
"in": "query",
"style": "form"
},
{
"name": "page",
"required": true,
"schema": {
"description": "Page number for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
},
{
"name": "page_size",
"required": true,
"schema": {
"description": "Page size for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Balance"
}
}
}
}
},
"400": {
"description": "A path parameter could not be parsed into its expected type.\n\nThe query string is missing a required parameter, or a parameter could not be parsed into its expected type."
},
"500": {
"description": "Possible reasons:\n- failed to convert asset balances\n- failed to get asset balances\n- failed to get user from database\n- invalid user verifier"
},
"404": {
"description": "unknown user"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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:\n- a base asset must have a Base fee or a non_base asset must have a NonBase fee, but not any other combination\n- amount must be positive\n- could not parse fee_amount\n- custody vendor not configured\n- fee_amount must be greater than or equal to zero\n- tag_memo is not supported for this asset\n- tag_memo is required for this asset\n- transaction with this external_id was already attempted\n- unknown asset_code"
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "Possible reasons:\n- attempt to verify existing contract failed\n- could not begin transactional query\n- database error\n- failed to build contract\n- failed to commit database transaction\n- failed to create transaction\n- failed to get asset code\n- failed to get recipient user address\n- failed to get recipient user vault\n- failed to get treasury user\n- failed to look up connector\n- failed to look up recipient user\n- failed to save contract\n- treasury user is not configured"
},
"401": {
"description": "Not authenticated"
},
"403": {
"description": "the authority account cannot be used as the account for a transaction"
},
"404": {
"description": "Not found"
},
"409": {
"description": "user is archived"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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:\n- amount must be positive\n- could not parse amount: {body.amount}\n- transaction with this external_id was already attempted\n- unknown asset_code\n- unknown recipient"
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"409": {
"description": "recipient is archived"
},
"500": {
"description": "Possible reasons:\n- attempt to verify existing contract failed\n- could not begin transactional query\n- database error\n- failed to build contract\n- failed to commit database transaction\n- failed to create transaction\n- failed to get asset code\n- failed to save contract"
},
"401": {
"description": "Not authenticated"
},
"403": {
"description": "the authority account cannot be used as the account for a transaction"
},
"404": {
"description": "Not found"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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:\n- amount must be positive\n- asset code not configured for vendor\n- asset must not be a base asset\n- custody vendor not configured\n- transaction with this external_id was already attempted\n- vault not configured for user"
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "Possible reasons:\n- attempt to verify existing contract failed\n- could not begin transactional query\n- database error\n- failed to build contract\n- failed to commit database transaction\n- failed to create transaction\n- failed to get asset code\n- failed to get treasury user\n- failed to save contract\n- treasury user is not configured"
},
"401": {
"description": "Not authenticated"
},
"403": {
"description": "the authority account cannot be used as the account for a transaction"
},
"404": {
"description": "Not found"
},
"409": {
"description": "user is archived"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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:\n- amount must be positive\n- asset code not configured for vendor\n- asset must not be a base asset\n- custody vendor not configured\n- transaction with this external_id was already attempted"
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "Possible reasons:\n- attempt to verify existing contract failed\n- could not begin transactional query\n- database error\n- failed to build contract\n- failed to commit database transaction\n- failed to create transaction\n- failed to get asset code\n- failed to get treasury user\n- failed to save contract\n- treasury user is not configured"
},
"401": {
"description": "Not authenticated"
},
"403": {
"description": "the authority account cannot be used as the account for a transaction"
},
"404": {
"description": "Not found"
},
"409": {
"description": "user is archived"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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:\n- from_amount must be positive\n- unknown from asset_code\n- unknown to asset_code"
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "Possible reasons:\n- failed to get quote\n- failed to get quote amount\n- failed to get vendor asset code\n- failed to resolve from asset_code\n- failed to resolve to asset_code\n- missing ETH vendor asset code"
},
"401": {
"description": "Not authenticated"
},
"403": {
"description": "the authority account cannot be used as the account for a transaction"
},
"404": {
"description": "Not found"
},
"409": {
"description": "user is archived"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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:\n- amount must be positive\n- amount must not be negative\n- transaction with this external_id was already attempted\n- unknown from asset_code\n- unknown to asset_code"
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "Possible reasons:\n- attempt to verify existing contract failed\n- could not begin transactional query\n- failed to build contract\n- failed to commit database transaction\n- failed to create transaction\n- failed to get asset code\n- failed to get treasury user\n- failed to save contract\n- treasury user is not configured"
},
"401": {
"description": "Not authenticated"
},
"403": {
"description": "the authority account cannot be used as the account for a transaction"
},
"404": {
"description": "Not found"
},
"409": {
"description": "user is archived"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/users/{id}/transactions/onchain/swap": {
"post": {
"tags": [
"On-chain"
],
"summary": "Initiate new On-chain Swap Transaction",
"description": "Initiate a new atomic on-chain asset swap between two users.",
"operationId": "initiate_swap_txn",
"parameters": [
{
"name": "id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"in": "path",
"style": "simple"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InitiateSwapTxnRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InitiateSwapTxnResponse"
}
}
}
},
"400": {
"description": "Possible reasons:\n- counterparty user not found\n- custody vendor not configured\n- leg_a.amount must be positive\n- leg_b.amount must be positive\n- transaction with this external_id was already attempted\n- unknown asset_code for leg_a\n- unknown asset_code for leg_b"
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "Possible reasons:\n- attempt to verify existing contract failed\n- could not begin transactional query\n- failed to build swap contract\n- failed to commit database transaction\n- failed to create transaction\n- failed to get asset code for leg_a\n- failed to get asset code for leg_b\n- failed to get treasury user\n- failed to look up counterparty user\n- failed to look up source vault for leg_a\n- failed to look up source vault for leg_b\n- failed to save contract\n- treasury user is not configured"
},
"401": {
"description": "Not authenticated"
},
"403": {
"description": "the authority account cannot be used as the account for a transaction"
},
"404": {
"description": "Not found"
},
"409": {
"description": "user is archived"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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"
}
}
}
}
},
"400": {
"description": "A path parameter could not be parsed into its expected type."
},
"401": {
"description": "Not authenticated"
},
"404": {
"description": "Not found"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ContractTransactionV2"
}
}
}
}
},
"400": {
"description": "A path parameter could not be parsed into its expected type."
},
"401": {
"description": "Not authenticated"
},
"404": {
"description": "Not found"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/users/{id}/transactions": {
"get": {
"tags": [
"Transactions"
],
"summary": "List Transactions by User ID",
"description": "List the transactions for a given user, narrowed by the supplied filters and search term.",
"operationId": "list_contract_transactions",
"parameters": [
{
"name": "id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"in": "path",
"style": "simple"
},
{
"name": "search",
"schema": {
"description": "Text the sender's or receiver's username, or the transaction ID, must contain, matched\ncase-insensitively, matching every transaction when omitted. A term of one or two characters\nmust equal the whole value instead.",
"type": "string",
"pattern": "\\S",
"minLength": 1
},
"in": "query",
"style": "form"
},
{
"name": "contract_type",
"schema": {
"description": "Contract types to return transactions of, matching any one of them, returning every type\nwhen omitted.",
"type": "array",
"items": {
"$ref": "#/components/schemas/ContractType"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "from_user_id",
"schema": {
"description": "Sending users to return transactions of, matching any one of them, returning every\ntransaction when omitted.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "to_user_id",
"schema": {
"description": "Receiving users to return transactions of, matching any one of them, returning every\ntransaction when omitted.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "asset_code",
"schema": {
"description": "Asset codes (e.g. BTC) to return transactions of, matching any one of them, returning every\nasset when omitted.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "status",
"schema": {
"description": "Contract statuses to return transactions of, matching any one of them, returning every\nstatus when omitted.",
"type": "array",
"items": {
"$ref": "#/components/schemas/ContractStatus"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "sort_by",
"schema": {
"$ref": "#/components/schemas/ContractTransactionSort"
},
"in": "query",
"style": "form"
},
{
"name": "sort_dir",
"schema": {
"description": "Direction to order the results in, descending when omitted.",
"type": "string",
"enum": [
"asc",
"desc"
]
},
"in": "query",
"style": "form"
},
{
"name": "page",
"schema": {
"description": "Page number for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
},
{
"name": "page_size",
"schema": {
"description": "Page size for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"description": "A single page of results together with the position it was drawn from.",
"type": "object",
"properties": {
"data": {
"description": "The items in this page, ordered by the requested sort.",
"type": "array",
"items": {
"$ref": "#/components/schemas/ContractTransactionV2"
}
},
"page": {
"description": "Zero-based page number this result was drawn from.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 4294967295
},
"page_size": {
"description": "Maximum number of records the query paged by; an endpoint that pages over groups of rows can return more items than this.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 4294967295
},
"has_more": {
"description": "Whether at least one further page exists after this one.",
"type": "boolean"
},
"total_count": {
"description": "Total items matching the query, reported as zero when this page holds none.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 9223372036854775807
}
},
"required": [
"data",
"page",
"page_size",
"has_more",
"total_count"
]
}
}
}
},
"400": {
"description": "search term must not be blank\n\nThe query string is missing a required parameter, or a parameter could not be parsed into its expected type."
},
"500": {
"description": "Possible reasons:\n- failed to get transactions for user\n- failed to get user from database"
},
"404": {
"description": "unknown user"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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"
}
}
}
},
"400": {
"description": "A path parameter could not be parsed into its expected type."
},
"500": {
"description": "database error"
},
"401": {
"description": "Not authenticated"
},
"404": {
"description": "Not found"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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": {
"200": {
"description": "OK"
},
"400": {
"description": "The request body could not be parsed as JSON."
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "database error"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
},
"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": {
"200": {
"description": "OK"
},
"400": {
"description": "The request body could not be parsed as JSON."
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "database error"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/transactions": {
"get": {
"tags": [
"Transactions"
],
"summary": "List All Contract Transactions",
"description": "List all contract transactions, narrowed by the supplied filters and search term.",
"operationId": "list_all_contract_transactions",
"parameters": [
{
"name": "search",
"schema": {
"description": "Text the sender's or receiver's username, or the transaction ID, must contain, matched\ncase-insensitively, matching every transaction when omitted. A term of one or two characters\nmust equal the whole value instead.",
"type": "string",
"pattern": "\\S",
"minLength": 1
},
"in": "query",
"style": "form"
},
{
"name": "contract_type",
"schema": {
"description": "Contract types to return transactions of, matching any one of them, returning every type\nwhen omitted.",
"type": "array",
"items": {
"$ref": "#/components/schemas/ContractType"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "from_user_id",
"schema": {
"description": "Sending users to return transactions of, matching any one of them, returning every\ntransaction when omitted.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "to_user_id",
"schema": {
"description": "Receiving users to return transactions of, matching any one of them, returning every\ntransaction when omitted.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "asset_code",
"schema": {
"description": "Asset codes (e.g. BTC) to return transactions of, matching any one of them, returning every\nasset when omitted.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "status",
"schema": {
"description": "Contract statuses to return transactions of, matching any one of them, returning every\nstatus when omitted.",
"type": "array",
"items": {
"$ref": "#/components/schemas/ContractStatus"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "sort_by",
"schema": {
"$ref": "#/components/schemas/ContractTransactionSort"
},
"in": "query",
"style": "form"
},
{
"name": "sort_dir",
"schema": {
"description": "Direction to order the results in, descending when omitted.",
"type": "string",
"enum": [
"asc",
"desc"
]
},
"in": "query",
"style": "form"
},
{
"name": "page",
"schema": {
"description": "Page number for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
},
{
"name": "page_size",
"schema": {
"description": "Page size for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"description": "A single page of results together with the position it was drawn from.",
"type": "object",
"properties": {
"data": {
"description": "The items in this page, ordered by the requested sort.",
"type": "array",
"items": {
"$ref": "#/components/schemas/ContractTransactionV2"
}
},
"page": {
"description": "Zero-based page number this result was drawn from.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 4294967295
},
"page_size": {
"description": "Maximum number of records the query paged by; an endpoint that pages over groups of rows can return more items than this.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 4294967295
},
"has_more": {
"description": "Whether at least one further page exists after this one.",
"type": "boolean"
},
"total_count": {
"description": "Total items matching the query, reported as zero when this page holds none.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 9223372036854775807
}
},
"required": [
"data",
"page",
"page_size",
"has_more",
"total_count"
]
}
}
}
},
"400": {
"description": "search term must not be blank\n\nThe query string is missing a required parameter, or a parameter could not be parsed into its expected type."
},
"500": {
"description": "failed to get transactions"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/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_by_id",
"parameters": [
{
"name": "txn_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/ContractTransactionV2"
}
}
}
}
},
"400": {
"description": "A path parameter could not be parsed into its expected type."
},
"401": {
"description": "Not authenticated"
},
"404": {
"description": "Not found"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/transactions/{txn_id}/steps": {
"get": {
"tags": [
"Transactions"
],
"summary": "Get Steps for a Transaction by ID",
"description": "Get the execution steps for a transaction by ID.",
"operationId": "get_contract_transaction_steps",
"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/GetContractTransactionStepsResponse"
}
}
}
},
"400": {
"description": "A path parameter could not be parsed into its expected type."
},
"500": {
"description": "Possible reasons:\n- failed to convert execution steps\n- failed to get execution steps"
},
"401": {
"description": "Not authenticated"
},
"404": {
"description": "Not found"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/transactions/{txn_id}/status": {
"get": {
"tags": [
"Transactions"
],
"summary": "Get Status of a Transaction by ID",
"description": "Get the lifecycle status of a contract transaction by ID.",
"operationId": "get_contract_transaction_status",
"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/GetContractTransactionStatusResponse"
}
}
}
},
"400": {
"description": "A path parameter could not be parsed into its expected type."
},
"500": {
"description": "failed to get contract status"
},
"401": {
"description": "Not authenticated"
},
"404": {
"description": "Not found"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/transactions/{txn_id}/settlements": {
"get": {
"tags": [
"Transactions"
],
"summary": "List All Settlements for a Transaction",
"description": "List all settlements for a transaction.",
"operationId": "get_transaction_settlements",
"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/Settlements"
}
}
}
},
"400": {
"description": "A path parameter could not be parsed into its expected type."
},
"500": {
"description": "Possible reasons:\n- failed to convert settlements\n- failed to get settlements\n- failed to resolve users by verifier"
},
"401": {
"description": "Not authenticated"
},
"404": {
"description": "Not found"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/transactions/approval-requests": {
"get": {
"tags": [
"Transactions"
],
"summary": "List transaction approval requests",
"description": "List transaction approval requests, pending, approved and rejected, narrowed by the supplied\nfilters and search term.",
"operationId": "list_approval_requests",
"parameters": [
{
"name": "search",
"schema": {
"description": "Text the source or destination username, or the transaction ID, must contain, matched\ncase-insensitively, matching every request when omitted. A term of one or two characters\nmust equal the whole value instead.",
"type": "string",
"pattern": "\\S",
"minLength": 1
},
"in": "query",
"style": "form"
},
{
"name": "tx_type",
"schema": {
"description": "Transaction types to return requests for, matching any one of them, returning every type\nwhen omitted.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "source",
"schema": {
"description": "Source users to return requests for, matching any one of them, returning every request\nwhen omitted.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "destination",
"schema": {
"description": "Destination users to return requests for, matching any one of them, returning every request\nwhen omitted.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "asset_code",
"schema": {
"description": "Asset codes (e.g. BTC) to return requests for, matching any one of them, returning every\nasset when omitted.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "status",
"schema": {
"description": "Statuses to return requests in, matching any one of them, returning every status when\nomitted.",
"type": "array",
"items": {
"$ref": "#/components/schemas/ApprovalRequestStatus"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "completed_by",
"schema": {
"description": "Usernames of the operators who completed the requests to return, matching any one of them,\nreturning every request when omitted.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "sort_by",
"schema": {
"$ref": "#/components/schemas/ApprovalRequestSort"
},
"in": "query",
"style": "form"
},
{
"name": "sort_dir",
"schema": {
"description": "Direction to order the results in, descending when omitted.",
"type": "string",
"enum": [
"asc",
"desc"
]
},
"in": "query",
"style": "form"
},
{
"name": "page",
"schema": {
"description": "Page number for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
},
{
"name": "page_size",
"schema": {
"description": "Page size for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"description": "A single page of results together with the position it was drawn from.",
"type": "object",
"properties": {
"data": {
"description": "The items in this page, ordered by the requested sort.",
"type": "array",
"items": {
"$ref": "#/components/schemas/ApprovalRequest"
}
},
"page": {
"description": "Zero-based page number this result was drawn from.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 4294967295
},
"page_size": {
"description": "Maximum number of records the query paged by; an endpoint that pages over groups of rows can return more items than this.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 4294967295
},
"has_more": {
"description": "Whether at least one further page exists after this one.",
"type": "boolean"
},
"total_count": {
"description": "Total items matching the query, reported as zero when this page holds none.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 9223372036854775807
}
},
"required": [
"data",
"page",
"page_size",
"has_more",
"total_count"
]
}
}
}
},
"400": {
"description": "search term must not be blank\n\nThe query string is missing a required parameter, or a parameter could not be parsed into its expected type."
},
"500": {
"description": "failed to get approval requests from database"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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"
}
}
}
},
"400": {
"description": "A path parameter could not be parsed into its expected type."
},
"500": {
"description": "failed to get unapproved transaction from database"
},
"404": {
"description": "unknown approval request"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApprovalCompletionRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "A path parameter could not be parsed into its expected type."
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "failed to approve transaction"
},
"401": {
"description": "Not authenticated"
},
"404": {
"description": "Not found"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApprovalCompletionRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "A path parameter could not be parsed into its expected type."
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "failed to reject transaction"
},
"401": {
"description": "Not authenticated"
},
"404": {
"description": "Not found"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/admin/asset-codes": {
"get": {
"tags": [
"Admin"
],
"summary": "List Registered Asset Codes",
"description": "List registered asset codes, narrowed by the supplied filters and search term.",
"operationId": "get_asset_codes",
"parameters": [
{
"name": "search",
"schema": {
"description": "Text the asset code must contain, matched case-insensitively, matching every asset code\nwhen omitted. A term of one or two characters must equal the whole code instead.",
"type": "string",
"pattern": "\\S",
"minLength": 1
},
"in": "query",
"style": "form"
},
{
"name": "asset_code",
"schema": {
"description": "Asset codes (e.g. BTC) to return, matching any one of them exactly, returning every asset\ncode when omitted.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "vendor",
"schema": {
"description": "Vendors to return asset codes for, keeping a code that has a vendor code for any one of\nthem, returning every asset code when omitted.",
"type": "array",
"items": {
"$ref": "#/components/schemas/Vendor"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "disabled",
"schema": {
"description": "Whether to return disabled asset codes rather than enabled ones, returning enabled ones when\nomitted. Only `true` or `false` is accepted, so a blank value is a `400` rather than no\nfilter.",
"type": "boolean"
},
"in": "query",
"style": "form"
},
{
"name": "sort_by",
"schema": {
"$ref": "#/components/schemas/AssetCodeSort"
},
"in": "query",
"style": "form"
},
{
"name": "sort_dir",
"schema": {
"description": "Direction to order the results in, ascending when omitted.",
"type": "string",
"enum": [
"asc",
"desc"
]
},
"in": "query",
"style": "form"
},
{
"name": "page",
"schema": {
"description": "Page number for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
},
{
"name": "page_size",
"schema": {
"description": "Page size for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"description": "A single page of results together with the position it was drawn from.",
"type": "object",
"properties": {
"data": {
"description": "The items in this page, ordered by the requested sort.",
"type": "array",
"items": {
"$ref": "#/components/schemas/AssetCode"
}
},
"page": {
"description": "Zero-based page number this result was drawn from.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 4294967295
},
"page_size": {
"description": "Maximum number of records the query paged by; an endpoint that pages over groups of rows can return more items than this.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 4294967295
},
"has_more": {
"description": "Whether at least one further page exists after this one.",
"type": "boolean"
},
"total_count": {
"description": "Total items matching the query, reported as zero when this page holds none.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 9223372036854775807
}
},
"required": [
"data",
"page",
"page_size",
"has_more",
"total_count"
]
}
}
}
},
"400": {
"description": "search term must not be blank\n\nThe query string is missing a required parameter, or a parameter could not be parsed into its expected type."
},
"500": {
"description": "Possible reasons:\n- database error\n- database error: invalid rate lookup configuration\n- database error: invalid token data"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
},
"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": {
"200": {
"description": "OK"
},
"400": {
"description": "Possible reasons:\n- duplicate asset_code: {asset.asset_code}\n- unknown base_asset: {base_asset}\n- unsupported vendor: custody client is not configured"
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "Possible reasons:\n- custody client not configured\n- failed to activate asset in omnibus vault: {vendor_code.code}\n- failed to activate asset: {vendor_code}\n- failed to get existing asset vendor codes\n- failed to look up base asset\n- failed to serialize asset data\n- failed to serialize token data\n- failed to set asset codes\n- failed to set asset vendor code\n- failed to update price cache"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/admin/asset-codes/disabled": {
"get": {
"tags": [
"Admin"
],
"summary": "Get Disabled Asset Code Information",
"description": "Get information about disabled asset codes.",
"operationId": "get_disabled_asset_codes",
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AssetCode"
}
}
}
}
},
"500": {
"description": "Possible reasons:\n- database error\n- database error: invalid rate lookup configuration\n- database error: invalid token data"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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"
}
}
}
},
"400": {
"description": "A path parameter could not be parsed into its expected type."
},
"500": {
"description": "failed to disable asset code"
},
"401": {
"description": "Not authenticated"
},
"404": {
"description": "Not found"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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"
}
}
}
},
"400": {
"description": "A path parameter could not be parsed into its expected type."
},
"500": {
"description": "failed to delete asset vendor code"
},
"401": {
"description": "Not authenticated"
},
"404": {
"description": "Not found"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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\ntransferring 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:\n- amount must be positive\n- memo cannot be empty: e.g. \"authorized by User A\"\n- unknown asset_code"
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "Possible reasons:\n- could not begin transactional query\n- failed to build contract\n- failed to commit database transaction\n- failed to create transaction\n- failed to get to asset_code\n- failed to get user from database\n- failed to save contract"
},
"404": {
"description": "Possible reasons:\n- unknown recipient user\n- unknown user"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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. Comma-separated vendor identifiers.",
"type": "string",
"format": "comma-separated-array"
},
"in": "query",
"style": "form"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": {
"type": "string",
"format": "decimal",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
}
}
}
}
},
"400": {
"description": "A path parameter could not be parsed into its expected type.\n\nThe query string is missing a required parameter, or a parameter could not be parsed into its expected type."
},
"401": {
"description": "Not authenticated"
},
"500": {
"description": "failed to get vendor asset codes"
},
"404": {
"description": "Not found"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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": "Zero-based page number, defaulting to zero.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
},
{
"name": "page_size",
"schema": {
"description": "Page size, defaulting to 50 when omitted or zero, and capped at 200.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
},
{
"name": "vendors",
"schema": {
"description": "Legacy comma-delimited custody integration filter; empty means unfiltered. Intersects with\n`vendor` when both are supplied. Prefer repeatable `vendor` for new clients. Comma-separated vendor identifiers.",
"type": "string",
"format": "comma-separated-array"
},
"in": "query",
"style": "form"
},
{
"name": "vendor",
"schema": {
"description": "Exact custody integration filter, sent as repeated query keys or an MCP array.",
"type": "array",
"items": {
"$ref": "#/components/schemas/CustodyVendor"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "asset_code",
"schema": {
"description": "Exact asset code filter, sent as repeated query keys or an MCP array.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "search",
"schema": {
"description": "Case-insensitive search across vendor name and both asset codes; one or two characters\nmatch a whole field, longer terms match anywhere, and blank terms are rejected.",
"type": "string",
"pattern": "\\S",
"minLength": 1
},
"in": "query",
"style": "form"
},
{
"name": "sort_by",
"schema": {
"$ref": "#/components/schemas/VendorBalanceSortKey"
},
"in": "query",
"style": "form"
},
{
"name": "sort_dir",
"schema": {
"description": "Sort direction, defaulting to ascending; tie-breakers remain ascending.",
"type": "string",
"enum": [
"asc",
"desc"
]
},
"in": "query",
"style": "form"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"description": "A page of successfully retrieved vendor balances; failed vendors are logged and omitted, so counts do not guarantee complete custody totals.",
"type": "object",
"properties": {
"data": {
"description": "The items in this page, ordered by the requested sort.",
"type": "array",
"items": {
"$ref": "#/components/schemas/AllVendorAssetBalanceResponse"
}
},
"page": {
"description": "Zero-based page number this result was drawn from.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 4294967295
},
"page_size": {
"description": "Maximum number of records the query paged by; an endpoint that pages over groups of rows can return more items than this.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 4294967295
},
"has_more": {
"description": "Whether at least one further page exists after this one.",
"type": "boolean"
},
"total_count": {
"description": "Total matching rows from successfully retrieved vendors, including when the requested page is empty; failed vendors are excluded.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 9223372036854775807
},
"sort_by": {
"$ref": "#/components/schemas/VendorBalanceSortKey"
},
"sort_dir": {
"description": "Direction a sort key orders results in.",
"type": "string",
"enum": [
"asc",
"desc"
]
}
},
"required": [
"data",
"page",
"page_size",
"has_more",
"total_count",
"sort_by",
"sort_dir"
]
}
}
}
},
"400": {
"description": "The query string is missing a required parameter, or a parameter could not be parsed into its expected type.\n\nsearch term must not be blank"
},
"401": {
"description": "Not authenticated"
},
"500": {
"description": "failed to get vendor asset codes"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/admin/contracts": {
"get": {
"tags": [
"Admin"
],
"summary": "List All Contracts",
"description": "List all contracts, narrowed by the supplied filters and search term.",
"operationId": "list_all_contracts",
"parameters": [
{
"name": "search",
"schema": {
"description": "Text the contract ID must contain, matched case-insensitively, matching every contract when\nomitted. A term of one or two characters must equal the whole ID instead.",
"type": "string",
"pattern": "\\S",
"minLength": 1
},
"in": "query",
"style": "form"
},
{
"name": "contract_type",
"schema": {
"description": "Contract types to return, matching any one of them, returning every type when omitted.",
"type": "array",
"items": {
"$ref": "#/components/schemas/ContractType"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "status",
"schema": {
"description": "Statuses to return contracts in, matching any one of them, returning every status when\nomitted.",
"type": "array",
"items": {
"$ref": "#/components/schemas/ContractStatus"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "digital_twin_only",
"schema": {
"description": "Whether to return only contracts that involve only digital twins (transfers, issues and\nredeems) or only those that do not, returning both when omitted. Only `true` or `false` is\naccepted, so a blank value is a `400` rather than no filter.",
"type": "boolean"
},
"in": "query",
"style": "form"
},
{
"name": "sort_by",
"schema": {
"$ref": "#/components/schemas/ContractSort"
},
"in": "query",
"style": "form"
},
{
"name": "sort_dir",
"schema": {
"description": "Direction to order the results in, descending when omitted.",
"type": "string",
"enum": [
"asc",
"desc"
]
},
"in": "query",
"style": "form"
},
{
"name": "page",
"schema": {
"description": "Page number for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
},
{
"name": "page_size",
"schema": {
"description": "Page size for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"description": "A single page of results together with the position it was drawn from.",
"type": "object",
"properties": {
"data": {
"description": "The items in this page, ordered by the requested sort.",
"type": "array",
"items": {
"$ref": "#/components/schemas/ContractInfo"
}
},
"page": {
"description": "Zero-based page number this result was drawn from.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 4294967295
},
"page_size": {
"description": "Maximum number of records the query paged by; an endpoint that pages over groups of rows can return more items than this.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 4294967295
},
"has_more": {
"description": "Whether at least one further page exists after this one.",
"type": "boolean"
},
"total_count": {
"description": "Total items matching the query, reported as zero when this page holds none.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 9223372036854775807
}
},
"required": [
"data",
"page",
"page_size",
"has_more",
"total_count"
]
}
}
}
},
"400": {
"description": "search term must not be blank\n\nThe query string is missing a required parameter, or a parameter could not be parsed into its expected type."
},
"500": {
"description": "Possible reasons:\n- failed to convert type\n- failed to get contracts from database"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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"
}
}
}
},
"400": {
"description": "Possible reasons:\n- amount must be positive\n- asset_code must not be blank\n- invalid amount\n- invalid source vendor\n- tag_memo is not supported for this asset\n- tag_memo is required for this asset"
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "Possible reasons:\n- failed to get asset code from database\n- failed to get vendor code from database\n- transaction failed: {msg}\n- unable to create transaction"
},
"404": {
"description": "Possible reasons:\n- unknown asset code\n- unknown vendor code"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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"
}
}
}
},
"400": {
"description": "The request body could not be parsed as JSON."
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "failed to resend notifications"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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"
}
}
}
},
"400": {
"description": "The request body could not be parsed as JSON."
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "failed to resend failed transactions"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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": "search",
"schema": {
"description": "Text a username must contain, matched case-insensitively, matching every user when omitted.\nA term of one or two characters must equal the whole username instead, so `an` finds `AN`\nbut not `Daniel`.",
"type": "string",
"pattern": "\\S",
"minLength": 1
},
"in": "query",
"style": "form"
},
{
"name": "id",
"schema": {
"description": "Users to return, matching any one of them, returning every user when omitted.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "verifier",
"schema": {
"description": "Wallet verifiers to return the users of, matching any one of them, returning every user\nwhen omitted.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "user_type",
"schema": {
"description": "Roles to return users of, matching any one of them, returning every role when omitted.",
"type": "array",
"items": {
"$ref": "#/components/schemas/UserTypeFilter"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "asset_code",
"schema": {
"description": "Assets a returned user must hold an address in at least one of, returning every user when\nomitted.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "vendor",
"schema": {
"description": "Vendors a returned user must have an identity at at least one of, returning every user when\nomitted.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "include_archived",
"schema": {
"description": "Whether to list archived users alongside active ones.",
"type": "boolean"
},
"in": "query",
"style": "form"
},
{
"name": "sort_by",
"schema": {
"$ref": "#/components/schemas/UserSort"
},
"in": "query",
"style": "form"
},
{
"name": "sort_dir",
"schema": {
"description": "Direction to order the results in.",
"type": "string",
"enum": [
"asc",
"desc"
]
},
"in": "query",
"style": "form"
},
{
"name": "page",
"schema": {
"description": "Page number for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
},
{
"name": "page_size",
"schema": {
"description": "Page size for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"description": "A single page of results together with the position it was drawn from.",
"type": "object",
"properties": {
"data": {
"description": "The items in this page, ordered by the requested sort.",
"type": "array",
"items": {
"$ref": "#/components/schemas/AllUsersAssetsResponse"
}
},
"page": {
"description": "Zero-based page number this result was drawn from.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 4294967295
},
"page_size": {
"description": "Maximum number of records the query paged by; an endpoint that pages over groups of rows can return more items than this.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 4294967295
},
"has_more": {
"description": "Whether at least one further page exists after this one.",
"type": "boolean"
},
"total_count": {
"description": "Total items matching the query, reported as zero when this page holds none.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 9223372036854775807
}
},
"required": [
"data",
"page",
"page_size",
"has_more",
"total_count"
]
}
}
}
},
"400": {
"description": "The query string is missing a required parameter, or a parameter could not be parsed into its expected type."
},
"500": {
"description": "failed to get all users from database"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/admin/users/addresses": {
"get": {
"tags": [
"Admin"
],
"summary": "List All Addresses for User",
"description": "List every user's addresses, narrowed by the supplied filters and search terms.",
"operationId": "list_all_addresses",
"parameters": [
{
"name": "username",
"schema": {
"description": "Text a username must contain, matched case-insensitively, matching every username when\nomitted. A term of one or two characters must equal the whole username instead.",
"type": "string",
"pattern": "\\S",
"minLength": 1
},
"in": "query",
"style": "form"
},
{
"name": "address",
"schema": {
"description": "Text an address must contain, matched case-insensitively, matching every address when\nomitted. A term of one or two characters must equal the whole address instead.",
"type": "string",
"pattern": "\\S",
"minLength": 1
},
"in": "query",
"style": "form"
},
{
"name": "user_id",
"schema": {
"description": "Users whose addresses to return, matching any one of them, returning every user's when\nomitted.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "asset_code",
"schema": {
"description": "Asset codes to return addresses for, matching any one of them, returning every asset's when\nomitted.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "vendor",
"schema": {
"description": "Custody vendors to return addresses for, matching any one of them, returning every vendor's\nwhen omitted.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "vault_id",
"schema": {
"description": "Vaults to return addresses for, matching any one of them, returning every vault's when\nomitted.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "sort_by",
"schema": {
"$ref": "#/components/schemas/AddressSort"
},
"in": "query",
"style": "form"
},
{
"name": "sort_dir",
"schema": {
"description": "Direction to order the results in.",
"type": "string",
"enum": [
"asc",
"desc"
]
},
"in": "query",
"style": "form"
},
{
"name": "page",
"schema": {
"description": "Page number for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
},
{
"name": "page_size",
"schema": {
"description": "Page size for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"description": "A single page of results together with the position it was drawn from.",
"type": "object",
"properties": {
"data": {
"description": "The items in this page, ordered by the requested sort.",
"type": "array",
"items": {
"$ref": "#/components/schemas/UsernameAddress"
}
},
"page": {
"description": "Zero-based page number this result was drawn from.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 4294967295
},
"page_size": {
"description": "Maximum number of records the query paged by; an endpoint that pages over groups of rows can return more items than this.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 4294967295
},
"has_more": {
"description": "Whether at least one further page exists after this one.",
"type": "boolean"
},
"total_count": {
"description": "Total items matching the query, reported as zero when this page holds none.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 9223372036854775807
}
},
"required": [
"data",
"page",
"page_size",
"has_more",
"total_count"
]
}
}
}
},
"400": {
"description": "Possible reasons:\n- search term must not be blank\n- unknown vendor\n\nThe query string is missing a required parameter, or a parameter could not be parsed into its expected type."
},
"500": {
"description": "Possible reasons:\n- failed to get all address list\n- invalid vendor"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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": {
"description": "Optional asset code filter, matching any one of the codes named. Omit to include all assets.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "base_asset",
"schema": {
"description": "Optional exact filter on the base asset an asset settles into, matching any one of the base\nassets named. Omit to include all assets.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "search",
"schema": {
"description": "Optional case-insensitive search for text anywhere in the asset code. A term of one or two\ncharacters must equal the whole asset code instead. Omit to include all assets.",
"type": "string",
"pattern": "\\S",
"minLength": 1
},
"in": "query",
"style": "form"
},
{
"name": "disabled_assets",
"schema": {
"description": "Whether to return disabled assets instead of enabled ones, excluding them when omitted.",
"type": "boolean"
},
"in": "query",
"style": "form"
},
{
"name": "page",
"schema": {
"description": "Page number for paginated results, defaulting to the first page.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
},
{
"name": "page_size",
"schema": {
"description": "Page size for paginated results, defaulting to 50 and capped at 200.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
},
{
"name": "sort_by",
"schema": {
"$ref": "#/components/schemas/AssetBalanceSortKey"
},
"in": "query",
"style": "form"
},
{
"name": "sort_dir",
"schema": {
"description": "Direction the results are ordered in, defaulting to ascending.",
"type": "string",
"enum": [
"asc",
"desc"
]
},
"in": "query",
"style": "form"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"description": "A single page of results together with the position it was drawn from.",
"type": "object",
"properties": {
"data": {
"description": "The items in this page, ordered by the requested sort.",
"type": "array",
"items": {
"$ref": "#/components/schemas/AssetTotalBalance"
}
},
"page": {
"description": "Zero-based page number this result was drawn from.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 4294967295
},
"page_size": {
"description": "Maximum number of records the query paged by; an endpoint that pages over groups of rows can return more items than this.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 4294967295
},
"has_more": {
"description": "Whether at least one further page exists after this one.",
"type": "boolean"
},
"total_count": {
"description": "Total items matching the query, reported as zero when this page holds none.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 9223372036854775807
}
},
"required": [
"data",
"page",
"page_size",
"has_more",
"total_count"
]
}
}
}
},
"400": {
"description": "The query string is missing a required parameter, or a parameter could not be parsed into its expected type."
},
"500": {
"description": "failed to get asset total balances"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/admin/users/aum": {
"get": {
"tags": [
"Admin"
],
"summary": "Get Assets Under Management",
"description": "Returns exact USD AUM across every matching customer asset.",
"operationId": "get_aum",
"parameters": [
{
"name": "disabled_assets",
"schema": {
"description": "Whether to value disabled assets rather than enabled assets.",
"type": "boolean"
},
"in": "query",
"style": "form"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AumSummary"
}
}
}
},
"400": {
"description": "The query string is missing a required parameter, or a parameter could not be parsed into its expected type."
},
"500": {
"description": "failed to get AUM balances"
},
"503": {
"description": "USD rates unavailable for asset codes: {asset_codes}"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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": {
"description": "Optional asset code filter, matching any one of the codes named. Omit to include all assets.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "user_id",
"schema": {
"description": "Optional filter on the identifier of the user holding the balance, matching any one of the\nidentifiers named.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "verifier",
"schema": {
"description": "Optional exact filter on the wallet verifier of the user holding the balance, matching any\none of the verifiers named.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "username",
"schema": {
"description": "Optional case-insensitive search for text anywhere in the username of the user holding the\nbalance. A term of one or two characters must equal the whole username instead.",
"type": "string",
"pattern": "\\S",
"minLength": 1
},
"in": "query",
"style": "form"
},
{
"name": "disabled_assets",
"schema": {
"description": "Whether to return disabled assets instead of enabled ones, excluding them when omitted.",
"type": "boolean"
},
"in": "query",
"style": "form"
},
{
"name": "page",
"schema": {
"description": "Page number for paginated results, defaulting to the first page.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
},
{
"name": "page_size",
"schema": {
"description": "Page size for paginated results, defaulting to 50 and capped at 200.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
},
{
"name": "sort_by",
"schema": {
"$ref": "#/components/schemas/UserBalanceSortKey"
},
"in": "query",
"style": "form"
},
{
"name": "sort_dir",
"schema": {
"description": "Direction the results are ordered in, defaulting to ascending.",
"type": "string",
"enum": [
"asc",
"desc"
]
},
"in": "query",
"style": "form"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"description": "A single page of results together with the position it was drawn from.",
"type": "object",
"properties": {
"data": {
"description": "The items in this page, ordered by the requested sort.",
"type": "array",
"items": {
"$ref": "#/components/schemas/UserAssetBalance"
}
},
"page": {
"description": "Zero-based page number this result was drawn from.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 4294967295
},
"page_size": {
"description": "Maximum number of records the query paged by; an endpoint that pages over groups of rows can return more items than this.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 4294967295
},
"has_more": {
"description": "Whether at least one further page exists after this one.",
"type": "boolean"
},
"total_count": {
"description": "Total items matching the query, reported as zero when this page holds none.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 9223372036854775807
}
},
"required": [
"data",
"page",
"page_size",
"has_more",
"total_count"
]
}
}
}
},
"400": {
"description": "The query string is missing a required parameter, or a parameter could not be parsed into its expected type."
},
"500": {
"description": "failed to get user asset balances"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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",
"required": true,
"schema": {
"description": "Page number for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
},
{
"name": "page_size",
"required": true,
"schema": {
"description": "Page size for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/UserAddressBalance"
}
}
}
}
},
"400": {
"description": "The query string is missing a required parameter, or a parameter could not be parsed into its expected type."
},
"500": {
"description": "Possible reasons:\n- failed to get vault accounts\n- failed to get vault asset balances\n- failed to get vendor vaults\n- failed to parse amount\n- failed to parse custody amount\n- fiat provider is not supported\n- invalid vendor code\n- no vendor account found for address\n- no vendor vault found\n- vendor asset not found\n- vendor not supported"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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"
}
}
}
}
},
"400": {
"description": "The request body could not be parsed as JSON."
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/admin/webhooks/subscriptions": {
"get": {
"tags": [
"Webhooks"
],
"summary": "List webhook subscriptions",
"description": "List webhook subscriptions, narrowed by the supplied filters and search term.",
"operationId": "list_webhook_subscriptions",
"parameters": [
{
"name": "search",
"schema": {
"description": "Text the URL must contain, matched case-insensitively, matching every subscription when\nomitted. A term of one or two characters must equal the whole URL instead.",
"type": "string",
"pattern": "\\S",
"minLength": 1
},
"in": "query",
"style": "form"
},
{
"name": "active",
"schema": {
"description": "Whether to return only active or only inactive subscriptions, returning both when omitted.\nOnly `true` or `false` is accepted, so a blank value is a `400` rather than no filter.",
"type": "boolean"
},
"in": "query",
"style": "form"
},
{
"name": "sort_by",
"schema": {
"$ref": "#/components/schemas/WebhookSubscriptionSort"
},
"in": "query",
"style": "form"
},
{
"name": "sort_dir",
"schema": {
"description": "Direction to order the results in, descending when omitted.",
"type": "string",
"enum": [
"asc",
"desc"
]
},
"in": "query",
"style": "form"
},
{
"name": "page",
"schema": {
"description": "Page number for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
},
{
"name": "page_size",
"schema": {
"description": "Page size for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"description": "A single page of results together with the position it was drawn from.",
"type": "object",
"properties": {
"data": {
"description": "The items in this page, ordered by the requested sort.",
"type": "array",
"items": {
"$ref": "#/components/schemas/WebhookSubscription"
}
},
"page": {
"description": "Zero-based page number this result was drawn from.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 4294967295
},
"page_size": {
"description": "Maximum number of records the query paged by; an endpoint that pages over groups of rows can return more items than this.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 4294967295
},
"has_more": {
"description": "Whether at least one further page exists after this one.",
"type": "boolean"
},
"total_count": {
"description": "Total items matching the query, reported as zero when this page holds none.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 9223372036854775807
}
},
"required": [
"data",
"page",
"page_size",
"has_more",
"total_count"
]
}
}
}
},
"400": {
"description": "search term must not be blank\n\nThe query string is missing a required parameter, or a parameter could not be parsed into its expected type."
},
"500": {
"description": "database error"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
},
"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"
}
}
}
},
"400": {
"description": "The request body could not be parsed as JSON."
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "database error"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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"
}
}
}
},
"400": {
"description": "A path parameter could not be parsed into its expected type."
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "database error"
},
"401": {
"description": "Not authenticated"
},
"404": {
"description": "Not found"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
},
"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"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EmptyResponse"
}
}
}
},
"400": {
"description": "A path parameter could not be parsed into its expected type."
},
"409": {
"description": "webhook subscription still has deliveries"
},
"500": {
"description": "database error"
},
"401": {
"description": "Not authenticated"
},
"404": {
"description": "Not found"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/admin/webhooks/deliveries": {
"get": {
"tags": [
"Webhooks"
],
"summary": "List Webhook History",
"description": "List webhook history, narrowed by the supplied filters and search term.",
"operationId": "list_webhook_deliveries",
"parameters": [
{
"name": "search",
"schema": {
"description": "Text the target URL must contain, matched case-insensitively, matching every delivery when\nomitted. A term of one or two characters must equal the whole URL instead.",
"type": "string",
"pattern": "\\S",
"minLength": 1
},
"in": "query",
"style": "form"
},
{
"name": "delivery_status",
"schema": {
"description": "Delivery states to return, matching any one of them, returning every state when omitted.",
"type": "array",
"items": {
"$ref": "#/components/schemas/WebhookDeliveryStatus"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "subscription_id",
"schema": {
"description": "Subscriptions to return deliveries to, matching any one of them, returning every\nsubscription's when omitted.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "sort_by",
"schema": {
"$ref": "#/components/schemas/WebhookDeliverySort"
},
"in": "query",
"style": "form"
},
{
"name": "sort_dir",
"schema": {
"description": "Direction to order the results in, descending when omitted.",
"type": "string",
"enum": [
"asc",
"desc"
]
},
"in": "query",
"style": "form"
},
{
"name": "page",
"schema": {
"description": "Page number for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
},
{
"name": "page_size",
"schema": {
"description": "Page size for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"description": "A single page of results together with the position it was drawn from.",
"type": "object",
"properties": {
"data": {
"description": "The items in this page, ordered by the requested sort.",
"type": "array",
"items": {
"$ref": "#/components/schemas/WebhookDelivery"
}
},
"page": {
"description": "Zero-based page number this result was drawn from.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 4294967295
},
"page_size": {
"description": "Maximum number of records the query paged by; an endpoint that pages over groups of rows can return more items than this.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 4294967295
},
"has_more": {
"description": "Whether at least one further page exists after this one.",
"type": "boolean"
},
"total_count": {
"description": "Total items matching the query, reported as zero when this page holds none.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 9223372036854775807
}
},
"required": [
"data",
"page",
"page_size",
"has_more",
"total_count"
]
}
}
}
},
"400": {
"description": "search term must not be blank\n\nThe query string is missing a required parameter, or a parameter could not be parsed into its expected type."
},
"500": {
"description": "Possible reasons:\n- database error\n- invalid event type"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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"
}
}
}
},
"400": {
"description": "A path parameter could not be parsed into its expected type."
},
"500": {
"description": "database error"
},
"404": {
"description": "event not found"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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"
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "Possible reasons:\n- failed to get asset code\n- failed to get estimated fee"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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"
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "Possible reasons:\n- failed to get asset code\n- failed to get estimated fee"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/settlement": {
"get": {
"tags": [
"Settlement"
],
"summary": "Get Report Templates",
"description": "Get a list of report templates, narrowed by the supplied filters and search term.",
"operationId": "list_report_templates",
"parameters": [
{
"name": "search",
"schema": {
"description": "Text the template name must contain, matched case-insensitively, matching every template\nwhen omitted. A term of one or two characters must equal the whole name instead.",
"type": "string",
"pattern": "\\S",
"minLength": 1
},
"in": "query",
"style": "form"
},
{
"name": "root_participant",
"schema": {
"description": "Root participants to return templates for, matching any one of them, returning every\ntemplate when omitted.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "id",
"schema": {
"description": "Templates to return, matching any one of them, returning every template when omitted.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "sort_by",
"schema": {
"$ref": "#/components/schemas/ReportTemplateSort"
},
"in": "query",
"style": "form"
},
{
"name": "sort_dir",
"schema": {
"description": "Direction to order the results in, descending when omitted.",
"type": "string",
"enum": [
"asc",
"desc"
]
},
"in": "query",
"style": "form"
},
{
"name": "page",
"schema": {
"description": "Page number for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
},
{
"name": "page_size",
"schema": {
"description": "Page size for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"description": "A single page of results together with the position it was drawn from.",
"type": "object",
"properties": {
"data": {
"description": "The items in this page, ordered by the requested sort.",
"type": "array",
"items": {
"$ref": "#/components/schemas/ReportTemplate"
}
},
"page": {
"description": "Zero-based page number this result was drawn from.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 4294967295
},
"page_size": {
"description": "Maximum number of records the query paged by; an endpoint that pages over groups of rows can return more items than this.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 4294967295
},
"has_more": {
"description": "Whether at least one further page exists after this one.",
"type": "boolean"
},
"total_count": {
"description": "Total items matching the query, reported as zero when this page holds none.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 9223372036854775807
}
},
"required": [
"data",
"page",
"page_size",
"has_more",
"total_count"
]
}
}
}
},
"400": {
"description": "search term must not be blank\n\nThe query string is missing a required parameter, or a parameter could not be parsed into its expected type."
},
"500": {
"description": "failed to get report templates"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
},
"post": {
"tags": [
"Settlement"
],
"summary": "Add New Report Template",
"description": "Add a new report template. The report template defines the root participant that all\ncommitments must include as either a sender or recipient, as well as the other counterparties\nthat are included (if inclusive) or excluded (if not inclusive) in the commitments.",
"operationId": "add_report_template",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddReportTemplateRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddReportTemplateResponse"
}
}
}
},
"400": {
"description": "counterparties cannot be empty if inclusive"
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "Possible reasons:\n- database error\n- failed to insert report template"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/settlement/{id}/run": {
"post": {
"tags": [
"Settlement"
],
"summary": "Run a Report",
"description": "Run a report for a given report template with the provided period_end. The period_start of the\nreport is derived from the period_end of the last apply of the report for each asset.",
"operationId": "run_report",
"parameters": [
{
"name": "id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"in": "path",
"style": "simple"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunReportRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunReportResponse"
}
}
}
},
"400": {
"description": "period_end must be in the past"
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "Possible reasons:\n- failed to load report template\n- report execution failed"
},
"401": {
"description": "Not authenticated"
},
"404": {
"description": "Not found"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/settlement/{id}": {
"get": {
"tags": [
"Settlement"
],
"summary": "Get Report Template",
"description": "Get a report template by ID.",
"operationId": "get_report_template",
"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/ReportTemplate"
}
}
}
},
"400": {
"description": "A path parameter could not be parsed into its expected type."
},
"500": {
"description": "failed to get report template"
},
"404": {
"description": "unknown report template"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
},
"delete": {
"tags": [
"Settlement"
],
"summary": "Delete Report Template",
"description": "Delete a report template by ID.",
"operationId": "delete_report_template",
"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": "A path parameter could not be parsed into its expected type."
},
"500": {
"description": "Possible reasons:\n- database error\n- failed to delete report template"
},
"404": {
"description": "unknown report template"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/settlement/{id}/runs": {
"get": {
"tags": [
"Settlement"
],
"summary": "Get List of Report Runs",
"description": "Get a list of report runs by template ID.",
"operationId": "list_report_runs",
"parameters": [
{
"name": "id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"in": "path",
"style": "simple"
},
{
"name": "page",
"required": true,
"schema": {
"description": "Page number for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
},
{
"name": "page_size",
"required": true,
"schema": {
"description": "Page size for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ReportItem"
}
}
}
}
},
"400": {
"description": "A path parameter could not be parsed into its expected type.\n\nThe query string is missing a required parameter, or a parameter could not be parsed into its expected type."
},
"500": {
"description": "failed to get report runs"
},
"401": {
"description": "Not authenticated"
},
"404": {
"description": "Not found"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/settlement/{id}/runs/{run_id}": {
"get": {
"tags": [
"Settlement"
],
"summary": "Retrieve Report Run",
"description": "Get a report run by ID.",
"operationId": "get_report_run",
"parameters": [
{
"name": "id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"in": "path",
"style": "simple"
},
{
"name": "run_id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"in": "path",
"style": "simple"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReportItem"
}
}
}
},
"400": {
"description": "A path parameter could not be parsed into its expected type."
},
"500": {
"description": "failed to get report run"
},
"404": {
"description": "unknown report_run"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
},
"delete": {
"tags": [
"Settlement"
],
"summary": "Delete Report",
"description": "Delete a report by ID.",
"operationId": "delete_report_run",
"parameters": [
{
"name": "id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"in": "path",
"style": "simple"
},
{
"name": "run_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": "A path parameter could not be parsed into its expected type."
},
"500": {
"description": "Possible reasons:\n- database error\n- failed to delete report run"
},
"404": {
"description": "unknown report"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/settlement/{id}/runs/{run_id}/results": {
"get": {
"tags": [
"Settlement"
],
"summary": "Retrieve Results for Report",
"description": "Get a list of results for a report by ID.",
"operationId": "list_report_results",
"parameters": [
{
"name": "id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"in": "path",
"style": "simple"
},
{
"name": "run_id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"in": "path",
"style": "simple"
},
{
"name": "page",
"required": true,
"schema": {
"description": "Page number for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
},
{
"name": "page_size",
"required": true,
"schema": {
"description": "Page size for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ReportEntry"
}
}
}
}
},
"400": {
"description": "A path parameter could not be parsed into its expected type.\n\nThe query string is missing a required parameter, or a parameter could not be parsed into its expected type."
},
"500": {
"description": "failed to get results"
},
"401": {
"description": "Not authenticated"
},
"404": {
"description": "Not found"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/settlement/{id}/results": {
"get": {
"tags": [
"Settlement"
],
"summary": "Get Settlement History for Template",
"description": "Get settlement history for a template, returning applied and unapplied results grouped by period.\n\nPages over periods rather than result rows: `page_size` counts periods, `total_count` counts the\nperiods matching the filters, and a page carries every value of the periods it holds — so it can\nhold more entries than its size, because a period with both applied and unapplied values yields\none entry for each.",
"operationId": "list_template_results",
"parameters": [
{
"name": "id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"in": "path",
"style": "simple"
},
{
"name": "period_from",
"schema": {
"description": "Earliest period end to return, inclusive, in RFC3339 format; every earlier period is\nreturned too when omitted.",
"type": "string",
"format": "date-time"
},
"in": "query",
"style": "form"
},
{
"name": "period_to",
"schema": {
"description": "End of the period range, exclusive, in RFC3339 format; every later period is returned too\nwhen omitted.",
"type": "string",
"format": "date-time"
},
"in": "query",
"style": "form"
},
{
"name": "asset_code",
"schema": {
"description": "Asset codes to return values for, matching any one of them, returning every asset's when\nomitted. A period keeps its place only while it holds at least one matching value.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "applied",
"schema": {
"description": "Whether to return applied or unapplied values only, returning both when omitted.",
"type": "boolean"
},
"in": "query",
"style": "form"
},
{
"name": "sort_dir",
"schema": {
"description": "Direction to order the periods in, latest period first when omitted.",
"type": "string",
"enum": [
"asc",
"desc"
]
},
"in": "query",
"style": "form"
},
{
"name": "page",
"schema": {
"description": "Page number for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
},
{
"name": "page_size",
"schema": {
"description": "Page size for paginated results, counted in periods and capped at 200.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"description": "A single page of results together with the position it was drawn from.",
"type": "object",
"properties": {
"data": {
"description": "The items in this page, ordered by the requested sort.",
"type": "array",
"items": {
"$ref": "#/components/schemas/TemplateResult"
}
},
"page": {
"description": "Zero-based page number this result was drawn from.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 4294967295
},
"page_size": {
"description": "Maximum number of records the query paged by; an endpoint that pages over groups of rows can return more items than this.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 4294967295
},
"has_more": {
"description": "Whether at least one further page exists after this one.",
"type": "boolean"
},
"total_count": {
"description": "Total items matching the query, reported as zero when this page holds none.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 9223372036854775807
}
},
"required": [
"data",
"page",
"page_size",
"has_more",
"total_count"
]
}
}
}
},
"400": {
"description": "A path parameter could not be parsed into its expected type.\n\nThe query string is missing a required parameter, or a parameter could not be parsed into its expected type."
},
"500": {
"description": "failed to get template results"
},
"401": {
"description": "Not authenticated"
},
"404": {
"description": "Not found"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/settlement/{id}/runs/{run_id}/apply": {
"post": {
"tags": [
"Settlement"
],
"summary": "Mark Report as Applied",
"description": "Mark a report as APPLIED, optionally passing in the asset codes to be applied. If asset codes\nis empty all assets are marked as APPLIED.",
"operationId": "apply_report_run",
"parameters": [
{
"name": "id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"in": "path",
"style": "simple"
},
{
"name": "run_id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"in": "path",
"style": "simple"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApplyReportRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EmptyResponse"
}
}
}
},
"400": {
"description": "A path parameter could not be parsed into its expected type."
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"409": {
"description": "report run has no results to apply"
},
"500": {
"description": "Possible reasons:\n- database error\n- failed to apply report\n- failed to load report results\n- failed to load report run"
},
"404": {
"description": "report run not found"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/admin/connectors": {
"get": {
"tags": [
"Connectors"
],
"summary": "List Connectors",
"description": "List registered connectors, ordered by name.",
"operationId": "list_connectors",
"parameters": [
{
"name": "page",
"required": true,
"schema": {
"description": "Page number for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
},
{
"name": "page_size",
"required": true,
"schema": {
"description": "Page size for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Connector"
}
}
}
}
},
"400": {
"description": "The query string is missing a required parameter, or a parameter could not be parsed into its expected type."
},
"500": {
"description": "failed to list connectors"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
},
"post": {
"tags": [
"Connectors"
],
"summary": "Register Connector",
"description": "Register a connector under a name, or replace the one already registered under that name. Knova routes calls for that name to the service at `url`, which must implement the connector contract (see the Connector Specification).\n\nThis only records the URL. It is validated as an absolute HTTP(S) URL, but Knova does not contact the service, so check that it is reachable before routing traffic to it. Re-registering an existing name replaces its URL immediately.",
"operationId": "set_connector",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SetConnectorRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Connector"
}
}
}
},
"400": {
"description": "The connector name is empty."
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "Possible reasons:\n- database error\n- failed to store connector"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/admin/connectors/{name}": {
"get": {
"tags": [
"Connectors"
],
"summary": "Get Connector",
"description": "Get a registered connector by name, including its URL and when it was registered and last replaced.",
"operationId": "get_connector",
"parameters": [
{
"name": "name",
"required": true,
"schema": {
"type": "string"
},
"in": "path",
"style": "simple"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Connector"
}
}
}
},
"400": {
"description": "A path parameter could not be parsed into its expected type."
},
"500": {
"description": "failed to get connector"
},
"404": {
"description": "No connector is registered under that name."
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/workflow-templates": {
"get": {
"tags": [
"Workflow Templates"
],
"summary": "List Workflow Templates",
"description": "List the stored workflow contract templates without their definitions.\n\nEach entry carries the identifier, version, and description of one stored template version, so\na caller can pick the template that fits its request and then fetch that template's full\ndefinition by identifier.",
"operationId": "list_workflow_templates",
"parameters": [
{
"name": "page",
"required": true,
"schema": {
"description": "Page number for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
},
{
"name": "page_size",
"required": true,
"schema": {
"description": "Page size for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WorkflowTemplateSummary"
}
}
}
}
},
"400": {
"description": "The query string is missing a required parameter, or a parameter could not be parsed into its expected type."
},
"500": {
"description": "failed to list workflow templates"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
},
"post": {
"tags": [
"Workflow Templates"
],
"summary": "Set Workflow Template",
"description": "Store a workflow contract template, replacing any template already stored under the same\nidentifier and version.\n\nThe request body is the workflow template document itself; its `id`, `version`, and\n`description` fields become the stored template's identity and listing text, so the stored\nrecord can never disagree with the document it holds. The document is validated against the\nworkflow engine's schema before it is stored, so a template that could never execute is\nrejected up front rather than at contract execution time.\n\n`operator_selectable` is catalog metadata supplied as a query parameter and stored in its own\ncolumn rather than in the workflow document.\n\nWhat is stored is the validated document re-serialized, not the raw request body. The workflow\nengine ignores any field it does not model, so persisting the raw body would return fields on\nretrieval that were never validated and would never take effect.",
"operationId": "set_workflow_template",
"parameters": [
{
"name": "operator_selectable",
"schema": {
"description": "Whether operators may choose the template directly; defaults to true",
"type": "boolean"
},
"in": "query",
"style": "form"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkflowTemplateSummary"
}
}
}
},
"400": {
"description": "Possible reasons:\n- invalid template: {err}\n- template must declare a description\n- template version '{template.version}' is not a valid semantic version\n\nThe query string is missing a required parameter, or a parameter could not be parsed into its expected type."
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "Possible reasons:\n- database error\n- failed to serialize workflow template\n- failed to store workflow template"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/workflow-templates/{workflow_id}": {
"get": {
"tags": [
"Workflow Templates"
],
"summary": "Get Workflow Template",
"description": "Get a stored workflow contract template, including its full definition, by identifier.\n\nThe highest stored semantic version is returned unless a specific `version` is requested.",
"operationId": "get_workflow_template",
"parameters": [
{
"name": "workflow_id",
"required": true,
"schema": {
"type": "string"
},
"in": "path",
"style": "simple"
},
{
"name": "version",
"schema": {
"description": "Version of the template to return; the highest stored version is returned when omitted",
"type": "string",
"format": "semver",
"pattern": "^(0|[1-9][0-9]{0,18})\\.(0|[1-9][0-9]{0,18})\\.(0|[1-9][0-9]{0,18})(?:-((?:0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$"
},
"in": "query",
"style": "form"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkflowTemplate"
}
}
}
},
"400": {
"description": "version '{&*version}' is not a valid semantic version\n\nThe query string is missing a required parameter, or a parameter could not be parsed into its expected type."
},
"500": {
"description": "failed to get workflow template"
},
"404": {
"description": "unknown workflow template"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/workflow-templates/{workflow_id}/operator-selectable": {
"put": {
"tags": [
"Workflow Templates"
],
"summary": "Set Workflow Template Operator Selectable",
"description": "Set whether operators may choose one or every stored version of a workflow template.",
"operationId": "set_workflow_template_operator_selectable",
"parameters": [
{
"name": "workflow_id",
"required": true,
"schema": {
"type": "string"
},
"in": "path",
"style": "simple"
},
{
"name": "version",
"schema": {
"description": "Version to update; every stored version is updated when omitted",
"type": "string",
"format": "semver",
"pattern": "^(0|[1-9][0-9]{0,18})\\.(0|[1-9][0-9]{0,18})\\.(0|[1-9][0-9]{0,18})(?:-((?:0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$"
},
"in": "query",
"style": "form"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SetWorkflowTemplateOperatorSelectableRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WorkflowTemplateSummary"
}
}
}
}
},
"400": {
"description": "version '{&*version}' is not a valid semantic version\n\nThe query string is missing a required parameter, or a parameter could not be parsed into its expected type."
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "Possible reasons:\n- database error\n- failed to update workflow template"
},
"404": {
"description": "unknown workflow template"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/transactions/workflow": {
"post": {
"tags": [
"Contracts"
],
"summary": "Submit Workflow Contract",
"description": "Submit an assembled workflow contract instance for immediate execution.\n\nThe instance is executed by the already-registered `pkg:contract/[email protected]` behavior, so\nthis endpoint only assembles and signs the contract; it does not interpret the template.\n\nThe caller must include an inlined template (identity + document). Before signing, the handler\nloads the reviewed catalog entry for that template's `id` and `version` and replaces the\ninlined document with the stored definition so system role bindings and steps cannot be forged\nvia the request body. Roles and params are then checked against that stored template.",
"operationId": "submit_workflow_contract",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubmitWorkflowContractRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubmitWorkflowContractResponse"
}
}
}
},
"400": {
"description": "Possible reasons:\n- \n- invalid template: {err}\n- invalid workflow instance data: {err}\n- transaction with this external_id was already attempted\n- unknown participant 'USER_ID'\n- unknown workflow template '{workflow_id}' version '{version}'\n- workflow template id is required\n- workflow template version is required"
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "Possible reasons:\n- \n- attempt to verify existing contract failed\n- could not begin transactional query\n- failed to build contract\n- failed to commit database transaction\n- failed to create transaction\n- failed to load workflow template\n- failed to save contract\n- stored workflow template is invalid"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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:\n- amount must be positive\n- transaction with this external_id was already attempted"
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "Possible reasons:\n- attempt to verify existing contract failed\n- could not begin transactional query\n- database error\n- failed to build contract\n- failed to commit database transaction\n- failed to create transaction\n- failed to deserialize fiat provider config\n- failed to save contract"
},
"404": {
"description": "Possible reasons:\n- \n- fiat provider config not found for `to`\n- fiat provider config not found for `user_id`\n- financial account not configured"
},
"401": {
"description": "Not authenticated"
},
"403": {
"description": "the authority account cannot be used as the account for a transaction"
},
"409": {
"description": "user is archived"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/users/{id}/identity": {
"get": {
"tags": [
"Identity"
],
"summary": "Get 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/UserIdentity"
}
}
}
},
"400": {
"description": "A path parameter could not be parsed into its expected type."
},
"500": {
"description": "Possible reasons:\n- database error\n- invalid identity data"
},
"404": {
"description": "no identity for user"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
},
"post": {
"tags": [
"Identity"
],
"summary": "Set Identity",
"description": "Store a user's identity data.",
"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/Identity"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SetIdentityResponse"
}
}
}
},
"400": {
"description": "A path parameter could not be parsed into its expected type."
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "Possible reasons:\n- database error\n- failed to serialize identity data"
},
"404": {
"description": "unknown user"
},
"401": {
"description": "Not authenticated"
},
"409": {
"description": "user is archived"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
},
"delete": {
"tags": [
"Identity"
],
"summary": "Delete Identity",
"description": "Clear the stored identity data 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"
}
}
}
},
"400": {
"description": "A path parameter could not be parsed into its expected type."
},
"500": {
"description": "database error"
},
"404": {
"description": "unknown user"
},
"401": {
"description": "Not authenticated"
},
"409": {
"description": "user is archived"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/admin/users/identities": {
"get": {
"tags": [
"Identity"
],
"summary": "List User Identities",
"description": "Get a list of user identities, narrowed by the supplied filters and search term.",
"operationId": "list_identities",
"parameters": [
{
"name": "search",
"schema": {
"description": "Text the name, first name, last name, username or email must contain, matched\ncase-insensitively, matching every user when omitted. A term of one or two characters must\nequal the whole value instead.",
"type": "string",
"pattern": "\\S",
"minLength": 1
},
"in": "query",
"style": "form"
},
{
"name": "name",
"schema": {
"description": "Names to return, as first and last name joined by a space, matching any one of them\nexactly, returning every user when omitted.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "username",
"schema": {
"description": "Usernames to return, matching any one of them exactly, returning every user when omitted.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "email",
"schema": {
"description": "Email addresses to return, matching any one of them exactly, returning every user when\nomitted.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "phone",
"schema": {
"description": "Phone numbers to return, matching any one of them exactly, returning every user when\nomitted.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "tax_id",
"schema": {
"description": "Tax IDs to return, matching any one of them exactly, returning every user when omitted.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"in": "query",
"style": "form"
},
{
"name": "sort_by",
"schema": {
"$ref": "#/components/schemas/IdentitySort"
},
"in": "query",
"style": "form"
},
{
"name": "sort_dir",
"schema": {
"description": "Direction to order the results in, descending when omitted.",
"type": "string",
"enum": [
"asc",
"desc"
]
},
"in": "query",
"style": "form"
},
{
"name": "page",
"schema": {
"description": "Page number for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
},
{
"name": "page_size",
"schema": {
"description": "Page size for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"description": "A single page of results together with the position it was drawn from.",
"type": "object",
"properties": {
"data": {
"description": "The items in this page, ordered by the requested sort.",
"type": "array",
"items": {
"$ref": "#/components/schemas/ListedUserIdentity"
}
},
"page": {
"description": "Zero-based page number this result was drawn from.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 4294967295
},
"page_size": {
"description": "Maximum number of records the query paged by; an endpoint that pages over groups of rows can return more items than this.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 4294967295
},
"has_more": {
"description": "Whether at least one further page exists after this one.",
"type": "boolean"
},
"total_count": {
"description": "Total items matching the query, reported as zero when this page holds none.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 9223372036854775807
}
},
"required": [
"data",
"page",
"page_size",
"has_more",
"total_count"
]
}
}
}
},
"400": {
"description": "search term must not be blank\n\nThe query string is missing a required parameter, or a parameter could not be parsed into its expected type."
},
"500": {
"description": "database error"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/users/{id}/identity/{vendor}": {
"post": {
"tags": [
"Identity"
],
"summary": "Set Vendor Identity",
"description": "Submit the stored identity data to a vendor and record the result.",
"operationId": "set_vendor_identity",
"parameters": [
{
"name": "id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"in": "path",
"style": "simple"
},
{
"name": "vendor",
"required": true,
"schema": {
"$ref": "#/components/schemas/VendorTarget"
},
"in": "path",
"style": "simple"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SetVendorIdentityRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SetVendorIdentityResponse"
}
}
}
},
"400": {
"description": "unsupported vendor: integration is not configured"
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"409": {
"description": "Possible reasons:\n- several vendor identities match this user; remove the duplicates at the vendor\n- the vendor identity matching this user ({identity_id}) already belongs to another user"
},
"500": {
"description": "Possible reasons:\n- database error\n- failed to set identity\n- invalid identity data"
},
"404": {
"description": "no identity for user"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
},
"delete": {
"tags": [
"Identity"
],
"summary": "Delete Vendor Identity",
"description": "Delete a user's identity from a vendor and remove the local record.",
"operationId": "delete_vendor_identity",
"parameters": [
{
"name": "id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"in": "path",
"style": "simple"
},
{
"name": "vendor",
"required": true,
"schema": {
"$ref": "#/components/schemas/VendorTarget"
},
"in": "path",
"style": "simple"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EmptyResponse"
}
}
}
},
"400": {
"description": "unsupported vendor: {vendor}"
},
"500": {
"description": "Possible reasons:\n- database error\n- failed to build fiat ramp configuration\n- failed to delete fiat ramp identity\n- failed to get fiat ramp configuration\n- failed to parse identity data"
},
"404": {
"description": "no vendor identity for user"
},
"401": {
"description": "Not authenticated"
},
"409": {
"description": "user is archived"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/users/{id}/identity/{vendor}/tos": {
"get": {
"tags": [
"Identity"
],
"summary": "Get Identity TOS Link",
"description": "Get the Terms of Service link for a user's vendor identity.",
"operationId": "get_tos_link",
"parameters": [
{
"name": "id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"in": "path",
"style": "simple"
},
{
"name": "vendor",
"required": true,
"schema": {
"$ref": "#/components/schemas/VendorTarget"
},
"in": "path",
"style": "simple"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetTosLinkResponse"
}
}
}
},
"400": {
"description": "A path parameter could not be parsed into its expected type."
},
"500": {
"description": "Possible reasons:\n- database error\n- failed to parse identity data"
},
"404": {
"description": "no vendor identity for user"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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:\n- could not parse amount: {body.amount}\n- identity must accept terms of service\n- unknown asset_code\n- vendor asset not configured for fiat ramp"
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "Possible reasons:\n- database error\n- failed to build fiat ramp configuration\n- failed to get asset code\n- failed to get fiat ramp configuration\n- failed to get to asset_code\n- failed to parse identity data\n- failed to set up asset for user"
},
"404": {
"description": "Possible reasons:\n- unknown user\n- user identity not found"
},
"401": {
"description": "Not authenticated"
},
"403": {
"description": "the authority account cannot be used as the account for a transaction"
},
"409": {
"description": "user is archived"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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:\n- could not parse amount: {body.amount}\n- identity must accept terms of service\n- unknown asset_code\n- vendor asset not configured for fiat ramp"
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "Possible reasons:\n- database error\n- failed to build fiat ramp configuration\n- failed to get asset code\n- failed to get fiat ramp configuration\n- failed to get to asset_code\n- failed to parse identity data\n- failed to set up asset for user"
},
"404": {
"description": "Possible reasons:\n- unknown user\n- user identity not found"
},
"401": {
"description": "Not authenticated"
},
"403": {
"description": "the authority account cannot be used as the account for a transaction"
},
"409": {
"description": "user is archived"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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",
"required": true,
"schema": {
"$ref": "#/components/schemas/FiatRampTxnType"
},
"in": "query",
"style": "form"
},
{
"name": "countryCode",
"required": true,
"schema": {
"$ref": "#/components/schemas/CountryCode"
},
"in": "query",
"style": "form"
},
{
"name": "fiatCurrency",
"required": true,
"schema": {
"$ref": "#/components/schemas/FiatCurrencyId"
},
"in": "query",
"style": "form"
},
{
"name": "assetCode",
"required": true,
"schema": {
"description": "Asset code",
"type": "string"
},
"in": "query",
"style": "form"
},
{
"name": "paymentMethod",
"schema": {
"description": "Payment method",
"allOf": [
{
"$ref": "#/components/schemas/PaymentMethod"
}
]
},
"in": "query",
"style": "form"
},
{
"name": "fromAmount",
"schema": {
"description": "From amount of the conversion, e.g 100.",
"type": "string"
},
"in": "query",
"style": "form"
},
{
"name": "toAmount",
"schema": {
"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:\n- either to_amount or from_amount should be specified\n- vendor asset not configured for fiat ramp\n\nThe query string is missing a required parameter, or a parameter could not be parsed into its expected type."
},
"500": {
"description": "Possible reasons:\n- failed to build fiat ramp configuration\n- failed to get asset code\n- failed to get fiat ramp configuration"
},
"412": {
"description": ""
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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"
}
}
}
},
"400": {
"description": "The request body could not be parsed as JSON."
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "Possible reasons:\n- OnOff ramp error\n- failed to get OnOff ramp configuration"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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"
}
}
}
},
"400": {
"description": "The request body could not be parsed as JSON."
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "Possible reasons:\n- OnOff ramp error\n- failed to get OnOff ramp configuration"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/users/{id}/payment-accounts": {
"get": {
"tags": [
"Payment Accounts"
],
"summary": "List payment accounts",
"description": "List payment accounts for a user.",
"operationId": "list_payment_accounts",
"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/PaymentAccount"
}
}
}
}
},
"400": {
"description": "A path parameter could not be parsed into its expected type."
},
"401": {
"description": "Not authenticated"
},
"404": {
"description": "Not found"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
},
"post": {
"tags": [
"Payment Accounts"
],
"summary": "Set payment account",
"description": "Set a payment account for a user.",
"operationId": "set_payment_account",
"parameters": [
{
"name": "id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"in": "path",
"style": "simple"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SetPaymentAccountRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SetPaymentAccountResponse"
}
}
}
},
"400": {
"description": "Possible reasons:\n- currency and country are required for a fiat payment instruction\n- user must already have an identity"
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "Possible reasons:\n- database error\n- failed to add payment instruction\n- failed to build fiat ramp configuration\n- failed to get fiat ramp configuration\n- failed to parse identity data\n- failed to save payment account\n- failed to serialize payment account\n- failed to serialize payment account data\n- failed to serialize payment instruction"
},
"401": {
"description": "Not authenticated"
},
"404": {
"description": "Not found"
},
"409": {
"description": "user is archived"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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:\n- \n- amount has sub-Gwei precision; provide at most 9 decimal places\n- asset_code not found\n- incorrect address format\n- incorrect amount\n- network needs to be configured for this asset_code\n- unable to parse vault_id"
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "Possible reasons:\n- bd post stake intent failed\n- configured network is not supported\n- could not begin transactional query\n- failed to build stake contract\n- failed to commit database transaction\n- failed to get treasury user\n- failed to save contract\n- failed to save staking position\n- failed to submit stake transaction\n- service not configured to support staking\n- treasury user is not configured\n- unable to connect to database\n- unable to create contract call data\n- unable to obtain vault info\n- unable to parse available amount\n- unable to parse staked amount\n- vault does not contain asset_code"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/unstake": {
"post": {
"tags": [
"Stake"
],
"summary": "Unstake Assets via Service Provider",
"description": "Unstakes assets using configured service provider\n\nValidates the `asset_code`, resolves the Ethereum network\nfrom the asset configuration, builds an unstake contract, and submits\nit for processing via the transaction manager.",
"operationId": "unstake",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnstakeRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnstakeResponse"
}
}
}
},
"400": {
"description": "Possible reasons:\n- asset_code not found\n- network needs to be configured for this asset_code"
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "Possible reasons:\n- could not begin transactional query\n- failed to build unstake contract\n- failed to commit database transaction\n- failed to get treasury user\n- failed to save contract\n- failed to submit unstake transaction\n- treasury user is not configured\n- unable to connect to database"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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",
"required": true,
"schema": {
"description": "Page number for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
},
{
"name": "page_size",
"required": true,
"schema": {
"description": "Page size for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"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\n\nThe query string is missing a required parameter, or a parameter could not be parsed into its expected type."
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
},
"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"
}
}
}
},
"400": {
"description": "The request body could not be parsed as JSON."
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"409": {
"description": "external address already registered"
},
"500": {
"description": "Possible reasons:\n- failed to look up address in database\n- failed to save address in database"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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"
}
}
}
}
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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:\n- failed to initiate buy product\n- incorrect amount\n- unknown base_asset_code"
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "Possible reasons:\n- failed to get asset code from database\n- failed to get user from database"
},
"404": {
"description": "Possible reasons:\n- check /products for supported options\n- unknown user"
},
"401": {
"description": "Not authenticated"
},
"409": {
"description": "user is archived"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/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- \n- asset_code not found\n- base_asset_code not found\n- incorrect amount\n- token_asset_code not found"
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "Possible reasons:\n- failed to get user from database\n- failed to serialize product approve\n- failed to serialize teller sell\n- unable to connect to database"
},
"404": {
"description": "Possible reasons:\n- check /products for supported options\n- unknown user"
},
"401": {
"description": "Not authenticated"
},
"409": {
"description": "user is archived"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/auth/users": {
"get": {
"tags": [
"Auth"
],
"summary": "List auth users",
"description": "List users from the auth provider (Keycloak).",
"operationId": "list_auth_users",
"parameters": [
{
"name": "page",
"required": true,
"schema": {
"description": "Page number for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
},
{
"name": "page_size",
"required": true,
"schema": {
"description": "Page size for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"in": "query",
"style": "form"
},
{
"name": "include_disabled",
"schema": {
"description": "When true, include disabled users in the results. Defaults to false.",
"type": "boolean"
},
"in": "query",
"style": "form"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AuthUser"
}
}
}
}
},
"400": {
"description": "Possible reasons:\n- page and page_size produce an offset that is too large\n- page_size is too large\n\nThe query string is missing a required parameter, or a parameter could not be parsed into its expected type."
},
"500": {
"description": "Possible reasons:\n- failed to connect to keycloak\n- failed to fetch user roles\n- failed to list auth users"
},
"503": {
"description": "keycloak not configured"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
},
"post": {
"tags": [
"Auth"
],
"summary": "Create auth user",
"description": "Create a new user in the auth provider (Keycloak).",
"operationId": "create_auth_user",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateAuthUserRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthUser"
}
}
}
},
"400": {
"description": "The request body could not be parsed as JSON."
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "Possible reasons:\n- failed to connect to keycloak\n- failed to create auth user"
},
"503": {
"description": "keycloak not configured"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/auth/roles": {
"get": {
"tags": [
"Auth"
],
"summary": "List auth roles",
"description": "List realm roles from the auth provider (Keycloak).",
"operationId": "list_auth_roles",
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AuthRole"
}
}
}
}
},
"500": {
"description": "Possible reasons:\n- failed to connect to keycloak\n- failed to fetch asset restrictions\n- failed to list auth roles"
},
"503": {
"description": "keycloak not configured"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/auth/users/USER_ID": {
"get": {
"tags": [
"Auth"
],
"summary": "Get auth user",
"description": "Get a single user from the auth provider (Keycloak) by ID.",
"operationId": "get_auth_user",
"parameters": [
{
"name": "user_id",
"required": true,
"schema": {
"type": "string"
},
"in": "path",
"style": "simple"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthUser"
}
}
}
},
"400": {
"description": "A path parameter could not be parsed into its expected type."
},
"500": {
"description": "Possible reasons:\n- failed to connect to keycloak\n- failed to fetch user roles"
},
"404": {
"description": "user 'USER_ID' not found"
},
"503": {
"description": "keycloak not configured"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
},
"put": {
"tags": [
"Auth"
],
"summary": "Update auth user",
"description": "Update an existing user in the auth provider (Keycloak).",
"operationId": "update_auth_user",
"parameters": [
{
"name": "user_id",
"required": true,
"schema": {
"type": "string"
},
"in": "path",
"style": "simple"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateAuthUserRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthUser"
}
}
}
},
"400": {
"description": "A path parameter could not be parsed into its expected type."
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "Possible reasons:\n- failed to connect to keycloak\n- failed to fetch user roles\n- failed to update auth user"
},
"404": {
"description": "user 'USER_ID' not found"
},
"503": {
"description": "keycloak not configured"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
},
"delete": {
"tags": [
"Auth"
],
"summary": "Delete auth user",
"description": "Delete a user from the auth provider (Keycloak) by ID.",
"operationId": "delete_auth_user",
"parameters": [
{
"name": "user_id",
"required": true,
"schema": {
"type": "string"
},
"in": "path",
"style": "simple"
}
],
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "A path parameter could not be parsed into its expected type."
},
"500": {
"description": "Possible reasons:\n- failed to connect to keycloak\n- failed to delete auth user"
},
"503": {
"description": "keycloak not configured"
},
"401": {
"description": "Not authenticated"
},
"404": {
"description": "Not found"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/auth/users/USER_ID/disable": {
"post": {
"tags": [
"Auth"
],
"summary": "Disable auth user",
"description": "Disable a user in the auth provider (Keycloak) by ID.",
"operationId": "disable_auth_user",
"parameters": [
{
"name": "user_id",
"required": true,
"schema": {
"type": "string"
},
"in": "path",
"style": "simple"
}
],
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "A path parameter could not be parsed into its expected type."
},
"500": {
"description": "Possible reasons:\n- failed to connect to keycloak\n- failed to disable auth user"
},
"404": {
"description": "user 'USER_ID' not found"
},
"503": {
"description": "keycloak not configured"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
},
"/v1/auth/users/USER_ID/roles": {
"post": {
"tags": [
"Auth"
],
"summary": "Add roles to auth user",
"description": "Add realm-level roles to an auth user.",
"operationId": "add_roles_to_user",
"parameters": [
{
"name": "user_id",
"required": true,
"schema": {
"type": "string"
},
"in": "path",
"style": "simple"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddRolesRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "A path parameter could not be parsed into its expected type."
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "Possible reasons:\n- failed to assign roles to user\n- failed to connect to keycloak"
},
"404": {
"description": "role '{name}' not found"
},
"503": {
"description": "keycloak not configured"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
},
"delete": {
"tags": [
"Auth"
],
"summary": "Remove roles from auth user",
"description": "Remove realm-level roles from an auth user.",
"operationId": "remove_roles_from_user",
"parameters": [
{
"name": "user_id",
"required": true,
"schema": {
"type": "string"
},
"in": "path",
"style": "simple"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RemoveRolesRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "A path parameter could not be parsed into its expected type."
},
"422": {
"description": "The request body is valid JSON but does not match the expected schema."
},
"500": {
"description": "Possible reasons:\n- failed to connect to keycloak\n- failed to remove roles from user"
},
"404": {
"description": "role '{name}' not found"
},
"503": {
"description": "keycloak not configured"
},
"401": {
"description": "Not authenticated"
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}
}
},
"components": {
"securitySchemes": {
"ApiKeyAuth": {
"type": "apiKey",
"in": "header",
"name": "x-api-key",
"description": "API key issued to service integrations."
},
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT",
"description": "JWT issued for an authenticated user."
}
},
"schemas": {
"AddReportTemplateRequest": {
"type": "object",
"properties": {
"name": {
"description": "Name of the report template",
"type": "string"
},
"root_participant": {
"description": "User ID of the participant that all settlements must include as either a sender or recipient",
"type": "string",
"format": "uuid"
},
"counterparties": {
"description": "User IDs of counterparties that are included (if inclusive) or excluded (if not inclusive)",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"inclusive": {
"description": "Whether the counterparties are inclusive or exclusive",
"type": "boolean"
}
},
"required": [
"name",
"root_participant",
"counterparties",
"inclusive"
]
},
"AddReportTemplateResponse": {
"type": "object",
"properties": {
"id": {
"description": "ID of the newly created report template",
"type": "string",
"format": "uuid"
}
},
"required": [
"id"
]
},
"AddRolesRequest": {
"type": "object",
"properties": {
"roles": {
"description": "The names of the realm-level roles to assign.",
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"roles"
]
},
"Address": {
"description": "On-chain destination or source address, with an optional tag/memo.",
"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"
]
},
"AddressSort": {
"type": "string",
"enum": [
"asset_code",
"username",
"created"
]
},
"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"
}
},
"vendors": {
"description": "List of vendors associated with the user",
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"id",
"username",
"verifier",
"user_type",
"address_info",
"vendors"
]
},
"AllVendorAssetBalanceParams": {
"description": "Query shaping for global custody balances, not balances belonging to a user.",
"type": "object",
"properties": {
"page": {
"description": "Zero-based page number, defaulting to zero.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"page_size": {
"description": "Page size, defaulting to 50 when omitted or zero, and capped at 200.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"vendors": {
"description": "Legacy comma-delimited custody integration filter; empty means unfiltered. Intersects with\n`vendor` when both are supplied. Prefer repeatable `vendor` for new clients. Comma-separated vendor identifiers.",
"type": "string",
"format": "comma-separated-array"
},
"vendor": {
"nullable": true,
"description": "Exact custody integration filter, sent as repeated query keys or an MCP array.",
"type": "array",
"items": {
"$ref": "#/components/schemas/CustodyVendor"
},
"minItems": 1,
"maxItems": 200
},
"asset_code": {
"nullable": true,
"description": "Exact asset code filter, sent as repeated query keys or an MCP array.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"search": {
"nullable": true,
"description": "Case-insensitive search across vendor name and both asset codes; one or two characters\nmatch a whole field, longer terms match anywhere, and blank terms are rejected.",
"type": "string",
"pattern": "\\S",
"minLength": 1
},
"sort_by": {
"$ref": "#/components/schemas/VendorBalanceSortKey"
},
"sort_dir": {
"description": "Sort direction, defaulting to ascending; tie-breakers remain ascending.",
"type": "string",
"enum": [
"asc",
"desc"
]
}
}
},
"AllVendorAssetBalanceResponse": {
"description": "Native balance of an enabled asset at a custody vendor or institution.",
"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",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
}
},
"required": [
"vendor",
"asset_code",
"asset_vendor_code",
"balance"
]
},
"AppendPolicyAuditEventRequest": {
"description": "Request to append a policy audit event.",
"type": "object",
"properties": {
"id": {
"description": "Unique audit event id.",
"type": "string",
"format": "uuid"
},
"event_type": {
"description": "Audit event type.",
"type": "string"
},
"kc_user_id": {
"nullable": true,
"description": "Keycloak user associated with the event; falls back to auth user.",
"type": "string",
"format": "uuid"
},
"agent_id": {
"nullable": true,
"description": "Agent associated with the event, when available.",
"type": "string",
"format": "uuid"
},
"session_id": {
"nullable": true,
"description": "Session associated with the event, when available.",
"type": "string",
"format": "uuid"
},
"decision_id": {
"nullable": true,
"description": "Policy decision associated with the event, when available.",
"type": "string",
"format": "uuid"
},
"rule_id": {
"nullable": true,
"description": "Policy rule associated with the event, when available.",
"type": "string",
"format": "uuid"
},
"payload_json": {
"description": "Event-specific JSON payload.",
"type": "object"
},
"created": {
"nullable": true,
"description": "Optional event creation timestamp override.",
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"event_type",
"payload_json"
]
},
"ApplyReportRequest": {
"type": "object",
"properties": {
"asset_codes": {
"description": "List of asset codes to be applied. If empty all asset codes are applied.",
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"asset_codes"
]
},
"ApprovalCompletionRequest": {
"type": "object",
"properties": {
"memo": {
"type": "string"
}
},
"required": [
"memo"
]
},
"ApprovalRequest": {
"description": "A transaction held for an operator to approve or reject.",
"type": "object",
"properties": {
"uetr": {
"description": "Unique End-to-end Transaction Reference of the held transaction.",
"type": "string",
"format": "uuid"
},
"idempotency_key": {
"description": "Idempotency key of the request that asked for approval.",
"type": "string",
"format": "uuid"
},
"approved": {
"nullable": true,
"description": "Whether the request was approved (`true`) or rejected (`false`); `null` while pending.",
"type": "boolean"
},
"completed_by": {
"nullable": true,
"description": "Username of the operator who approved or rejected the request; `null` while pending.",
"type": "string"
},
"created": {
"description": "When the request was created.",
"type": "string",
"format": "date-time"
},
"tx_type": {
"description": "Type of the held transaction.",
"type": "string"
},
"source": {
"description": "Source of the transaction, stored as text: usually the source user's ID, but any other\nvalue, such as `unknown`, is kept as it was stored.",
"type": "string"
},
"source_username": {
"nullable": true,
"description": "Username of the source user; `null` when `source` is not a known user ID.",
"type": "string"
},
"destination": {
"description": "Destination of the transaction, stored as text: usually the destination user's ID, but\nany other value, such as `unknown`, is kept as it was stored.",
"type": "string"
},
"destination_username": {
"nullable": true,
"description": "Username of the destination user; `null` when `destination` is not a known user ID.",
"type": "string"
},
"asset_code": {
"description": "Asset code of the transaction (e.g. BTC).",
"type": "string"
},
"amount": {
"description": "Amount of the transaction as a decimal string.",
"type": "string"
}
},
"required": [
"uetr",
"idempotency_key",
"created",
"tx_type",
"source",
"destination",
"asset_code",
"amount"
]
},
"ApprovalRequestSort": {
"type": "string",
"enum": [
"created",
"tx_type",
"source",
"destination",
"asset_code",
"amount",
"status",
"completed_by"
]
},
"ApprovalRequestStatus": {
"type": "string",
"enum": [
"pending",
"approved",
"rejected"
]
},
"AssetAum": {
"description": "One native asset total and the USD valuation derived from it.",
"type": "object",
"properties": {
"asset_code": {
"description": "Canonical asset code.",
"type": "string"
},
"base_asset": {
"nullable": true,
"description": "Base asset code this asset settles into, when applicable.",
"type": "string"
},
"holders": {
"description": "Number of distinct customers holding the asset.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 9223372036854775807
},
"total_amount": {
"description": "Total amount held in the asset's native unit.",
"type": "string",
"format": "decimal",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
},
"usd_rate": {
"description": "USD rate used for the valuation.",
"type": "string",
"format": "decimal",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
},
"usd_value": {
"description": "USD value of the native total.",
"type": "string",
"format": "decimal",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
}
},
"required": [
"asset_code",
"holders",
"total_amount",
"usd_rate",
"usd_value"
]
},
"AssetBalanceListParams": {
"type": "object",
"properties": {
"asset_code": {
"nullable": true,
"description": "Optional asset code filter, matching any one of the codes named. Omit to include all assets.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"base_asset": {
"nullable": true,
"description": "Optional exact filter on the base asset an asset settles into, matching any one of the base\nassets named. Omit to include all assets.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"search": {
"nullable": true,
"description": "Optional case-insensitive search for text anywhere in the asset code. A term of one or two\ncharacters must equal the whole asset code instead. Omit to include all assets.",
"type": "string",
"pattern": "\\S",
"minLength": 1
},
"disabled_assets": {
"description": "Whether to return disabled assets instead of enabled ones, excluding them when omitted.",
"type": "boolean"
},
"page": {
"description": "Page number for paginated results, defaulting to the first page.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"page_size": {
"description": "Page size for paginated results, defaulting to 50 and capped at 200.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"sort_by": {
"$ref": "#/components/schemas/AssetBalanceSortKey"
},
"sort_dir": {
"description": "Direction the results are ordered in, defaulting to ascending.",
"type": "string",
"enum": [
"asc",
"desc"
]
}
}
},
"AssetBalanceSortKey": {
"type": "string",
"enum": [
"asset_code",
"total_amount",
"holders"
]
},
"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\nto 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\nvaults in order to correlate the deposit to users.",
"type": "boolean"
},
"requires_tag_memo": {
"description": "Indicates that the asset requires destination tag/memo in addition to address.",
"type": "boolean"
},
"decimals": {
"description": "Number of decimals for asset (e.g. 18).",
"type": "integer",
"format": "int32",
"minimum": -32768,
"maximum": 32767
},
"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"
},
"rate_lookup": {
"$ref": "#/components/schemas/AssetCodeRateLookup"
},
"vendor_codes": {
"description": "Map of vendor identifier to vendor-specific info for the asset.",
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/VendorCodeInfo"
}
},
"token_data": {
"nullable": true,
"description": "Optional on-chain token addresses persisted in the `asset_codes.token_data` column.",
"allOf": [
{
"$ref": "#/components/schemas/TokenAssetData"
}
]
}
},
"required": [
"asset_code",
"requires_customer_vault",
"decimals",
"rate_lookup",
"vendor_codes"
]
},
"AssetCodeInput": {
"type": "object",
"properties": {
"asset_code": {
"description": "Asset code (e.g. BTC)",
"type": "string"
}
},
"required": [
"asset_code"
]
},
"AssetCodeListParams": {
"description": "Query parameters for listing asset codes.",
"type": "object",
"properties": {
"search": {
"nullable": true,
"description": "Text the asset code must contain, matched case-insensitively, matching every asset code\nwhen omitted. A term of one or two characters must equal the whole code instead.",
"type": "string",
"pattern": "\\S",
"minLength": 1
},
"asset_code": {
"nullable": true,
"description": "Asset codes (e.g. BTC) to return, matching any one of them exactly, returning every asset\ncode when omitted.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"vendor": {
"nullable": true,
"description": "Vendors to return asset codes for, keeping a code that has a vendor code for any one of\nthem, returning every asset code when omitted.",
"type": "array",
"items": {
"$ref": "#/components/schemas/Vendor"
},
"minItems": 1,
"maxItems": 200
},
"disabled": {
"nullable": true,
"description": "Whether to return disabled asset codes rather than enabled ones, returning enabled ones when\nomitted. Only `true` or `false` is accepted, so a blank value is a `400` rather than no\nfilter.",
"type": "boolean"
},
"sort_by": {
"$ref": "#/components/schemas/AssetCodeSort"
},
"sort_dir": {
"description": "Direction to order the results in, ascending when omitted.",
"type": "string",
"enum": [
"asc",
"desc"
]
},
"page": {
"description": "Page number for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"page_size": {
"description": "Page size for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
}
}
},
"AssetCodeRateLookup": {
"oneOf": [
{
"type": "object",
"properties": {
"DefaultUsdRate": {
"type": "string",
"format": "decimal",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
}
},
"required": [
"DefaultUsdRate"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"FetchAlias": {
"type": "string"
}
},
"required": [
"FetchAlias"
],
"additionalProperties": false
}
]
},
"AssetCodeSort": {
"type": "string",
"enum": [
"asset_code",
"vendor"
]
},
"AssetQuote": {
"type": "object",
"properties": {
"USD": {
"$ref": "#/components/schemas/AssetQuoteUsd"
}
},
"required": [
"USD"
]
},
"AssetQuoteUsd": {
"type": "object",
"properties": {
"price": {
"type": "number"
},
"volume_24h": {
"nullable": true,
"type": "number"
},
"cex_volume_24h": {
"nullable": true,
"type": "number"
},
"dex_volume_24h": {
"nullable": true,
"type": "number"
},
"volume_change_24h": {
"nullable": true,
"type": "number"
},
"percent_change_1h": {
"nullable": true,
"type": "number"
},
"percent_change_24h": {
"nullable": true,
"type": "number"
},
"percent_change_7d": {
"nullable": true,
"type": "number"
},
"percent_change_30d": {
"nullable": true,
"type": "number"
},
"percent_change_60d": {
"nullable": true,
"type": "number"
},
"percent_change_90d": {
"nullable": true,
"type": "number"
},
"market_cap": {
"nullable": true,
"type": "number"
},
"market_cap_dominance": {
"nullable": true,
"type": "number"
},
"fully_diluted_market_cap": {
"nullable": true,
"type": "number"
},
"tvl": {
"nullable": true,
"type": "number"
},
"last_updated": {
"type": "string"
}
},
"required": [
"price",
"last_updated"
]
},
"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",
"format": "int64",
"minimum": 0,
"maximum": 9223372036854775807
},
"total_amount": {
"description": "Total amount of this asset held by all users",
"type": "string",
"format": "decimal",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
}
},
"required": [
"asset_code",
"holders",
"total_amount"
]
},
"AumSummary": {
"description": "Exact AUM and the complete per-asset breakdown used to calculate it.",
"type": "object",
"properties": {
"total_usd_value": {
"description": "Sum of every per-asset USD value.",
"type": "string",
"format": "decimal",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
},
"assets": {
"description": "Per-asset values in deterministic asset-code order.",
"type": "array",
"items": {
"$ref": "#/components/schemas/AssetAum"
}
},
"valued_asset_count": {
"description": "Number of assets successfully valued.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 9223372036854775807
},
"total_asset_count": {
"description": "Number of assets in the native balance snapshot.",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 9223372036854775807
},
"balances_as_of": {
"description": "Time core completed the cached native balance aggregation.",
"type": "string",
"format": "date-time"
},
"valued_at": {
"description": "Time core combined the native balances with the currently cached rates.",
"type": "string",
"format": "date-time"
}
},
"required": [
"total_usd_value",
"assets",
"valued_asset_count",
"total_asset_count",
"balances_as_of",
"valued_at"
]
},
"AuthRole": {
"type": "object",
"properties": {
"id": {
"description": "Unique identifier for the role",
"type": "string"
},
"name": {
"description": "Name of the role",
"type": "string"
},
"description": {
"nullable": true,
"description": "Optional description of the role",
"type": "string"
},
"asset_restrictions": {
"description": "Asset trading restrictions associated with this role",
"type": "array",
"items": {
"$ref": "#/components/schemas/AssetRestrictions"
}
}
},
"required": [
"id",
"name",
"asset_restrictions"
]
},
"AuthUser": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"first_name": {
"nullable": true,
"type": "string"
},
"last_name": {
"nullable": true,
"type": "string"
},
"username": {
"nullable": true,
"type": "string"
},
"email": {
"nullable": true,
"type": "string"
},
"enabled": {
"type": "boolean"
},
"roles": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"id",
"enabled",
"roles"
]
},
"Balance": {
"type": "object",
"properties": {
"asset_code": {
"description": "Asset code (e.g. BTC)",
"type": "string"
},
"amount": {
"description": "Amount of the asset",
"type": "string",
"format": "decimal",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
}
},
"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": {
"bankSlug": {
"nullable": true,
"description": "The bank code for the account, such as a routing number or sort code",
"type": "string"
},
"bankAccountNumber": {
"nullable": true,
"description": "The bank account number",
"type": "string"
},
"localRoutingCode": {
"nullable": true,
"description": "Required for the following payment methods: BECS,FPS,IMPS_FIRC,EFT,TED. It may contain country-specific bank or branch identifiers such as branch code, transit number, BSB, IFSC, clearing code, or similar local routing codes.",
"type": "string"
},
"branchCode": {
"nullable": true,
"description": "A secondary local routing identifier used when a rail requires two codes, such as the branch code for JPY bank transfers or the transit number for CAD EFT.",
"type": "string"
},
"bankName": {
"nullable": true,
"description": "The name of the bank.",
"type": "string"
},
"swiftOrBicNumber": {
"nullable": true,
"description": "Beneficiary bank swift or bic number. Required for some regions",
"type": "string"
},
"accountHolderName": {
"nullable": true,
"description": "The name of the account holder. Required for Colombia.",
"type": "string"
},
"bankAccountType": {
"nullable": true,
"description": "The type of bank account.",
"allOf": [
{
"$ref": "#/components/schemas/BankAccountType"
}
]
},
"bankAccountNumberType": {
"nullable": true,
"description": "The type of bank account number. Required for Argentina.",
"allOf": [
{
"$ref": "#/components/schemas/BankAccountNumberType"
}
]
},
"address": {
"nullable": true,
"description": "Beneficiary bank address. Optional; required only for certain countries/corridors. The beneficiary's own address is taken from the identity.",
"allOf": [
{
"$ref": "#/components/schemas/PostalAddressCreateDto"
}
]
},
"recipientRelationship": {
"nullable": true,
"description": "The relationship between the sender and the recipient. Required by some payment providers.",
"allOf": [
{
"$ref": "#/components/schemas/RecipientRelationship"
}
]
},
"bankCode": {
"nullable": true,
"description": "DEPRECATED. The bank code for the account, such as a routing number or sort code.",
"type": "string"
},
"phone": {
"nullable": true,
"description": "DEPRECATED. The phone number associated with the bank account.",
"type": "string"
},
"taxId": {
"nullable": true,
"description": "DEPRECATED. The tax identification number associated with the account.",
"type": "string"
}
}
},
"BankDetailsEntity": {
"type": "object",
"properties": {
"bankName": {
"nullable": true,
"type": "string"
},
"bankSlug": {
"nullable": true,
"type": "string"
},
"bankAccountNumber": {
"nullable": true,
"description": "Full bank account number (PII). Nullable / omitted by default. Returned only when your organization has been granted access to full payment-instruction details. Contact support to enable.",
"type": "string"
},
"bankAccountNumberLast4": {
"type": "string"
},
"localRoutingCode": {
"nullable": true,
"type": "string"
},
"branchCode": {
"nullable": true,
"type": "string"
},
"swiftOrBicNumber": {
"nullable": true,
"type": "string"
},
"accountHolderName": {
"nullable": true,
"type": "string"
},
"bankAccountType": {
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/BankAccountType"
}
]
},
"bankAccountNumberType": {
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/BankAccountNumberType"
}
]
},
"address": {
"nullable": true,
"description": "Beneficiary bank address. The beneficiary's own address is taken from the identity.",
"allOf": [
{
"$ref": "#/components/schemas/PostalAddressEntity"
}
]
},
"bankRoutingNumber": {
"nullable": true,
"type": "string"
},
"bankCode": {
"nullable": true,
"type": "string"
},
"phone": {
"nullable": true,
"type": "string"
},
"taxId": {
"nullable": true,
"type": "string"
},
"recipientRelationship": {
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/RecipientRelationship"
}
]
}
},
"required": [
"bankAccountNumberLast4"
]
},
"BrebKeyDetailsCreateDto": {
"type": "object",
"properties": {
"brebKey": {
"description": "The Bre-B key value registered for the recipient.",
"type": "string"
}
},
"required": [
"brebKey"
]
},
"BrebKeyDetailsEntity": {
"type": "object",
"properties": {
"brebKey": {
"description": "The Bre-B key value registered for the recipient.",
"type": "string"
}
},
"required": [
"brebKey"
]
},
"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",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
},
"fee_level": {
"$ref": "#/components/schemas/FeeLevel"
},
"memo": {
"nullable": true,
"description": "Optional memo to attach to transaction.",
"type": "string"
},
"vendor": {
"nullable": true,
"description": "Optional backend vendor, defaults to default custody vendor",
"allOf": [
{
"$ref": "#/components/schemas/CustodyVendor"
}
]
}
},
"required": [
"external_id",
"asset_code",
"amount",
"fee_level"
]
},
"BurnResponse": {
"type": "object",
"properties": {
"id": {
"description": "Burn transaction ID.",
"type": "string",
"format": "uuid"
}
},
"required": [
"id"
]
},
"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"
]
},
"Connector": {
"description": "A registered connector: a name and the URL of the service that implements the connector contract.",
"type": "object",
"properties": {
"id": {
"description": "Unique identifier of the connector registration",
"type": "string",
"format": "uuid"
},
"name": {
"description": "Name the connector is registered under. Knova uses it to route calls to this connector.",
"type": "string"
},
"url": {
"description": "Base URL of the service that implements the connector contract.",
"type": "string"
},
"created": {
"description": "Timestamp at which the connector was first registered",
"type": "string",
"format": "date-time"
},
"updated": {
"description": "When the registration was last replaced.",
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"name",
"url",
"created",
"updated"
]
},
"ContractInfo": {
"type": "object",
"properties": {
"uetr": {
"description": "Unique End-to-end Transaction Reference",
"type": "string",
"format": "uuid"
},
"contract_type": {
"$ref": "#/components/schemas/ContractType"
},
"digital_twin_only": {
"description": "Indicates whether this contract only involves digital twins",
"type": "boolean"
},
"status": {
"$ref": "#/components/schemas/ContractStatus"
},
"status_info": {
"nullable": true,
"description": "Info about the status of the contract",
"type": "string"
},
"created": {
"description": "Timestamp when the contract was created",
"type": "string",
"format": "date-time"
}
},
"required": [
"uetr",
"contract_type",
"digital_twin_only",
"status",
"created"
]
},
"ContractSort": {
"type": "string",
"enum": [
"created",
"contract_type",
"digital_twin_only",
"status"
]
},
"ContractStatus": {
"type": "string",
"enum": [
"Initiated",
"Success",
"Failure",
"ManualRemediationRequired"
]
},
"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/WebhookPayloadDigitalTwinTransaction"
}
},
"digital_twin_summary": {
"description": "Summary of digital twin asset changes per user",
"type": "object",
"additionalProperties": {
"type": "object",
"additionalProperties": {
"type": "string",
"format": "decimal",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
}
}
},
"contract_type": {
"$ref": "#/components/schemas/ContractType"
},
"status": {
"description": "Status of the contract transaction",
"type": "string"
},
"status_info": {
"nullable": true,
"description": "Additional info about the transaction status",
"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"
]
},
"ContractTransactionSort": {
"type": "string",
"enum": [
"created",
"contract_type",
"source",
"destination",
"asset_code"
]
},
"ContractTransactionStep": {
"description": "A signed execution step recorded while processing a contract transaction.",
"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",
"format": "int64",
"minimum": 0,
"maximum": 4294967295
},
"previous_step_hash": {
"nullable": true,
"description": "Hash of the previous step, absent for the first step",
"type": "string"
},
"signature": {
"nullable": true,
"description": "Signature of step",
"type": "string"
},
"idempotency_key": {
"nullable": true,
"description": "Idempotency key used for step",
"type": "string"
},
"func_name": {
"nullable": true,
"description": "Name of adapter function called by step",
"type": "string"
},
"data": {
"description": "Data in JSON format",
"type": "object"
},
"created": {
"description": "Timestamp when step was created",
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"operation",
"operation_idx",
"data",
"created"
]
},
"ContractTransactionV2": {
"type": "object",
"properties": {
"uetr": {
"description": "Unique End-to-end Transaction Reference",
"type": "string",
"format": "uuid"
},
"to_user_id": {
"nullable": true,
"description": "User id receiving the assets",
"type": "string",
"format": "uuid"
},
"from_user_id": {
"nullable": true,
"description": "User id sending the assets",
"type": "string",
"format": "uuid"
},
"to_username": {
"nullable": true,
"description": "User id receiving the assets",
"type": "string"
},
"from_username": {
"nullable": true,
"description": "User id sending the assets",
"type": "string"
},
"to_address": {
"nullable": true,
"description": "Address receiving the assets",
"allOf": [
{
"$ref": "#/components/schemas/Address"
}
]
},
"from_address": {
"nullable": true,
"description": "Address sending the assets",
"allOf": [
{
"$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",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
},
"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",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
},
"fee_level": {
"nullable": true,
"description": "Fee level used for the transaction",
"allOf": [
{
"$ref": "#/components/schemas/FeeLevel"
}
]
},
"status": {
"$ref": "#/components/schemas/OnchainTransactionStatus"
},
"status_info": {
"nullable": true,
"description": "Info about the status of the transaction",
"type": "string"
},
"tx_hash": {
"nullable": true,
"description": "Transaction hash of the onchain transaction",
"type": "string"
},
"contract_type": {
"$ref": "#/components/schemas/ContractType"
},
"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": [
"uetr",
"asset_code",
"amount",
"fee_asset_code",
"network_fee",
"status",
"contract_type",
"created"
]
},
"ContractType": {
"type": "string",
"enum": [
"Withdraw",
"Deposit",
"Mint",
"Burn",
"Trade",
"Swap",
"Transfer",
"Issue",
"Redeem",
"Sweep",
"SweepFuel",
"Rebalance",
"Fiat",
"FiatOnRamp",
"FiatOffRamp",
"Stake",
"Unstake",
"LeveredDeposit",
"Workflow",
"Other"
]
},
"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",
"ZZ"
]
},
"CreateAddressRequest": {
"type": "object",
"properties": {
"asset_code": {
"description": "Asset code (e.g. BTC)",
"type": "string"
},
"vendor": {
"nullable": true,
"description": "Optional vendor where to create the address.",
"allOf": [
{
"$ref": "#/components/schemas/CustodyVendor"
}
]
}
},
"required": [
"asset_code"
]
},
"CreateAuthUserRequest": {
"type": "object",
"properties": {
"first_name": {
"nullable": true,
"description": "User first name",
"type": "string"
},
"last_name": {
"nullable": true,
"description": "User last name",
"type": "string"
},
"username": {
"description": "Unique username for the user",
"type": "string"
},
"email": {
"description": "User email address",
"type": "string"
},
"password": {
"nullable": true,
"description": "If provided, sets the user's initial password",
"type": "string"
}
},
"required": [
"username",
"email"
]
},
"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"
]
},
"CreateOrderResponse": {
"type": "object",
"properties": {
"order_reference": {
"type": "string"
}
},
"required": [
"order_reference"
]
},
"CreatePolicyDecisionRequest": {
"description": "Request to create or update a policy decision.",
"type": "object",
"properties": {
"id": {
"description": "Unique decision id.",
"type": "string",
"format": "uuid"
},
"session_id": {
"description": "Session associated with the decision.",
"type": "string",
"format": "uuid"
},
"kc_user_id": {
"nullable": true,
"description": "Keycloak user associated with the decision; falls back to auth user.",
"type": "string",
"format": "uuid"
},
"evaluation_context_json": {
"description": "JSON context evaluated by the policy engine.",
"type": "object"
},
"decision_outcome": {
"$ref": "#/components/schemas/PolicyDecisionOutcomeParam"
},
"reason": {
"description": "Human-readable reason for the decision.",
"type": "string"
},
"rule_id": {
"nullable": true,
"description": "Matching policy rule id, when a rule matched.",
"type": "string",
"format": "uuid"
},
"required_interaction_json": {
"nullable": true,
"description": "Interaction request payload required to continue, when applicable.",
"type": "object"
},
"status": {
"$ref": "#/components/schemas/InteractionStatusParam"
},
"response_json": {
"nullable": true,
"description": "Submitted response payload, when resolved.",
"type": "object"
},
"created": {
"nullable": true,
"description": "Optional creation timestamp override.",
"type": "string",
"format": "date-time"
},
"resolved": {
"nullable": true,
"description": "Decision resolution timestamp, when resolved.",
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"session_id",
"evaluation_context_json",
"decision_outcome",
"reason",
"status"
]
},
"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": {
"example": "custody_vendor_a",
"description": "Identifier of a configured custody vendor integration.",
"type": "string"
},
"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"
]
},
"DeletePolicyRuleResponse": {
"description": "Response returned after deleting a policy rule.",
"type": "object",
"properties": {
"deleted": {
"description": "True when a rule was deleted.",
"type": "boolean"
}
},
"required": [
"deleted"
]
},
"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 native ETH).",
"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)\nwhich can be either a BLS public key or an Ethereum account address. This parameter currently accepts ETH1 and BLS withdrawal credentials, but it is\nconsidered deprecated after the Capella/Shanghai fork. All users are now advised to use an ETH1 withdrawal address, specified through the\n`withdrawal_address` parameter as this is required to enable the ongoing accrual of rewards.\nFor more information regarding creating withdrawal credentials, please see the official\n[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",
"Initial",
"DigitalTwin",
"Onchain",
"Fiat",
"Final"
]
},
"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": {
"nullable": true,
"description": "Address receiving the assets",
"allOf": [
{
"$ref": "#/components/schemas/Address"
}
]
},
"from": {
"nullable": true,
"description": "Address sending the assets",
"allOf": [
{
"$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",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
},
"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",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
},
"fee_level": {
"nullable": true,
"description": "Fee level used for the transaction",
"allOf": [
{
"$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"
],
"additionalProperties": false
},
"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\ntreasury 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",
"PYG",
"DOP",
"UYU",
"BOB",
"CRC",
"GTQ",
"BWP",
"CDF",
"GHS",
"KES",
"MWK",
"NGN",
"RWF",
"ZAR",
"TZS",
"UGX",
"ZMW",
"XOF",
"XAF",
"AUD",
"BDT",
"CAD",
"INR",
"JPY",
"NPR",
"PKR",
"PHP",
"SGD",
"GBP",
"CNY",
"HKD",
"IDR",
"MYR",
"KRW",
"LKR",
"THB",
"TRY",
"VND",
"CZK",
"HUF",
"DKK",
"NOK",
"PLN",
"RON",
"RSD",
"SEK",
"CHF",
"AED",
"SAR",
"QAR",
"ILS",
"EGP",
"JOD",
"HNL",
"JMD",
"NZD",
"DZD",
"GMD",
"GNF",
"HTG",
"MAD",
"TND"
]
},
"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",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
},
"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"
]
},
"GetAumParams": {
"description": "Selects the enabled or disabled asset population included in AUM.",
"type": "object",
"properties": {
"disabled_assets": {
"description": "Whether to value disabled assets rather than enabled assets.",
"type": "boolean"
}
}
},
"GetContractTransactionStatusResponse": {
"description": "Response containing the lifecycle status of a contract transaction.",
"type": "object",
"properties": {
"status": {
"nullable": true,
"description": "Lifecycle status of the contract, absent when the contract is unknown.",
"allOf": [
{
"$ref": "#/components/schemas/ContractStatus"
}
]
}
}
},
"GetContractTransactionStepsResponse": {
"description": "Response containing the signed execution steps of a contract transaction.",
"type": "object",
"properties": {
"steps": {
"description": "Execution steps recorded for the transaction.",
"type": "array",
"items": {
"$ref": "#/components/schemas/ContractTransactionStep"
}
}
},
"required": [
"steps"
]
},
"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": {
"nullable": true,
"description": "Payment method",
"allOf": [
{
"$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"
]
},
"GetQuotesItem": {
"type": "object",
"properties": {
"symbol": {
"type": "string"
},
"quote": {
"$ref": "#/components/schemas/TokenQuote"
}
},
"required": [
"symbol",
"quote"
]
},
"GetQuotesParams": {
"type": "object",
"properties": {
"asset_codes": {
"description": "Comma-delimited string of crypto symbols using standard market tickers (e.g., \\\"BTC, ETH,LINK_ETH\\\"). Do NOT send a JSON array.",
"type": "string",
"format": "comma-separated-array"
}
}
},
"GetQuotesSuccessResponse": {
"type": "object",
"properties": {
"quotes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/QuotesSuccessResponse"
}
}
},
"required": [
"quotes"
]
},
"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",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
},
"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",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
},
"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",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
}
},
"required": [
"asset_code",
"amount"
]
},
"GetWorkflowTemplateParams": {
"description": "Query parameters selecting which stored version of a workflow template to return.",
"type": "object",
"properties": {
"version": {
"nullable": true,
"description": "Version of the template to return; the highest stored version is returned when omitted",
"type": "string",
"format": "semver",
"pattern": "^(0|[1-9][0-9]{0,18})\\.(0|[1-9][0-9]{0,18})\\.(0|[1-9][0-9]{0,18})(?:-((?:0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$"
}
}
},
"IbanBankDetailsEntity": {
"type": "object",
"properties": {
"bankSlug": {
"nullable": true,
"type": "string"
},
"iban": {
"nullable": true,
"description": "Full IBAN (PII). Nullable / omitted by default. Returned only when your organization has been granted access to full payment-instruction details. Contact support to enable.",
"type": "string"
},
"ibanLast4": {
"type": "string"
},
"localRoutingCode": {
"nullable": true,
"type": "string"
},
"swiftOrBicNumber": {
"nullable": true,
"type": "string"
},
"address": {
"nullable": true,
"description": "Beneficiary bank address.",
"allOf": [
{
"$ref": "#/components/schemas/PostalAddressEntity"
}
]
},
"bankAccountNumberLast4": {
"type": "string"
},
"bankName": {
"nullable": true,
"type": "string"
},
"bankRoutingNumber": {
"nullable": true,
"type": "string"
},
"bankCode": {
"nullable": true,
"type": "string"
},
"accountHolderName": {
"nullable": true,
"type": "string"
},
"bankAccountType": {
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/BankAccountType"
}
]
},
"recipientRelationship": {
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/RecipientRelationship"
}
]
},
"phone": {
"nullable": true,
"type": "string"
},
"taxId": {
"nullable": true,
"type": "string"
}
},
"required": [
"ibanLast4",
"bankAccountNumberLast4"
]
},
"IbanBankDetailsIbanCreateDto": {
"type": "object",
"properties": {
"bankSlug": {
"nullable": true,
"description": "The bank code for the account, such as a routing number or sort code",
"type": "string"
},
"localRoutingCode": {
"nullable": true,
"description": "Country-specific bank or branch identifier. Required by corridors whose IBAN alone does not identify the bank, such as Denmark and Norway.",
"type": "string"
},
"swiftOrBicNumber": {
"nullable": true,
"description": "Beneficiary bank swift or bic number. Required by corridors that pair an IBAN with a SWIFT code, such as the UAE and Poland.",
"type": "string"
},
"iban": {
"nullable": true,
"description": "The bank account number",
"type": "string"
},
"bankAccountNumber": {
"nullable": true,
"description": "The domestic account number behind the IBAN. Required by corridors that ask for both, such as Norway.",
"type": "string"
},
"bankName": {
"nullable": true,
"description": "The name of the bank. Required by PFIs that identify the institution by name rather than by code — payouts without it may be rejected.",
"type": "string"
},
"address": {
"nullable": true,
"description": "Beneficiary bank address. Optional; required only for certain countries/corridors. The beneficiary's own address is taken from the identity.",
"allOf": [
{
"$ref": "#/components/schemas/PostalAddressCreateDto"
}
]
}
}
},
"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"
},
"address": {
"nullable": true,
"description": "The address is deprecated in Identifier Payment Instruction and will be removed in future releases.",
"allOf": [
{
"$ref": "#/components/schemas/PostalAddressCreateDto"
}
]
}
},
"required": [
"identifierType",
"identifierValue"
]
},
"IdentifierDetailsEntity": {
"type": "object",
"properties": {
"identifierType": {
"$ref": "#/components/schemas/PaymentInstructionIdentifierType"
},
"identifierValue": {
"type": "string"
},
"address": {
"nullable": true,
"description": "The address associated with the Identifier Payment Instruction is deprecated.",
"allOf": [
{
"$ref": "#/components/schemas/PostalAddressEntity"
}
]
}
},
"required": [
"identifierType",
"identifierValue"
]
},
"Identity": {
"description": "Core identity data stored in the `users.identity_data` column.",
"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"
},
"nationalIdNumber": {
"nullable": true,
"description": "The national identification number",
"type": "string"
},
"nationalIdExpirationDate": {
"nullable": true,
"description": "The national identification expiration date",
"type": "string",
"format": "date"
},
"dateOfBirth": {
"description": "The date of birth",
"type": "string",
"format": "date"
},
"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": {
"nullable": true,
"description": "The sex",
"allOf": [
{
"$ref": "#/components/schemas/Sex"
}
]
},
"citizenship": {
"nullable": true,
"description": "Citizenship country code",
"type": "string"
},
"occupationCode": {
"nullable": true,
"description": "Occupation code",
"type": "string"
},
"employmentStatus": {
"nullable": true,
"description": "The employment status",
"allOf": [
{
"$ref": "#/components/schemas/EmploymentStatus"
}
]
},
"sourceOfFunds": {
"nullable": true,
"description": "Primary source of funds",
"allOf": [
{
"$ref": "#/components/schemas/PersonalSourceOfFunds"
}
]
},
"accountPurpose": {
"nullable": true,
"description": "Primary purpose of the account",
"allOf": [
{
"$ref": "#/components/schemas/PersonalAccountPurpose"
}
]
},
"accountPurposeOther": {
"nullable": true,
"description": "Other account purpose (required if accountPurpose is 'Other')",
"type": "string"
},
"monthlyAmounts": {
"nullable": true,
"description": "The expected monthly amounts on the account in USD",
"allOf": [
{
"$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"
}
},
"required": [
"firstName",
"lastName",
"dateOfBirth",
"address"
]
},
"IdentityDocumentCreateDto": {
"type": "object",
"properties": {
"issuingCountry": {
"$ref": "#/components/schemas/CountryCode"
},
"type": {
"$ref": "#/components/schemas/IdentityDocumentType"
},
"subType": {
"nullable": true,
"description": "The sub-type of the document. If provided with ProofOfAddress, must be a valid IdentityDocumentSubType.",
"allOf": [
{
"$ref": "#/components/schemas/IdentityDocumentSubType"
}
]
},
"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.",
"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.",
"type": "string"
}
},
"required": [
"issuingCountry",
"type",
"issuedDate"
]
},
"IdentityDocumentSubType": {
"type": "string",
"enum": [
"UtilityBill",
"BankStatement",
"RentalAgreement",
"TaxDocument",
"GovernmentCorrespondence"
]
},
"IdentityDocumentType": {
"type": "string",
"enum": [
"Passport",
"DriverLicense",
"NationalId",
"ResidencePermit",
"Formation",
"Ownership",
"ProofOfAddress",
"SourceOfFunds",
"IndividualHolding",
"BVN_NG",
"Selfie",
"Aadhaar",
"PAN",
"TaxId",
"LetterOfAuthority",
"EvidenceOfGoodStanding",
"ProofOfNatureOfBusiness",
"ProofOfVerification",
"BusinessLicense",
"AmlPolicy",
"FlowOfFunds",
"Other"
]
},
"IdentitySort": {
"type": "string",
"enum": [
"created",
"name",
"username",
"email",
"phone",
"tax_id"
]
},
"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": {
"nullable": true,
"description": "Optional memo for the transaction",
"type": "string"
}
},
"required": [
"external_id",
"asset_code",
"recipient_id",
"amount"
]
},
"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",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
},
"fee": {
"$ref": "#/components/schemas/Fee"
},
"memo": {
"nullable": true,
"description": "Optional memo to attach to transaction.",
"type": "string"
},
"vendor": {
"nullable": true,
"description": "Optional backend vendor, defaults to default custody vendor",
"allOf": [
{
"$ref": "#/components/schemas/CustodyVendor"
}
]
}
},
"required": [
"external_id",
"asset_code",
"to",
"amount",
"fee"
]
},
"InitiateOnchainTxnResponse": {
"type": "object",
"properties": {
"id": {
"description": "Onchain transaction ID",
"type": "string",
"format": "uuid"
}
},
"required": [
"id"
]
},
"InitiateSwapTxnRequest": {
"description": "Carries the information required to initiate an atomic two-asset swap between two users.",
"type": "object",
"properties": {
"external_id": {
"description": "Unique ID to ensure idempotency",
"type": "string"
},
"counterparty_user_id": {
"description": "ID of the counterparty user (the other side of the swap)",
"type": "string",
"format": "uuid"
},
"leg_a": {
"$ref": "#/components/schemas/SwapLegRequest"
},
"leg_b": {
"$ref": "#/components/schemas/SwapLegRequest"
},
"memo": {
"nullable": true,
"description": "Optional memo to attach to the contract",
"type": "string"
}
},
"required": [
"external_id",
"counterparty_user_id",
"leg_a",
"leg_b"
]
},
"InitiateSwapTxnResponse": {
"description": "Returns the identifier of the submitted swap contract transaction.",
"type": "object",
"properties": {
"id": {
"description": "Swap transaction 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",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
},
"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",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
},
"memo": {
"nullable": true,
"description": "Optional memo to attach to transaction.",
"type": "string"
}
},
"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"
},
"paymentAccountId": {
"type": "string",
"format": "uuid"
},
"paymentPurpose": {
"$ref": "#/components/schemas/PaymentPurpose"
}
},
"required": [
"externalId",
"fiatCurrency",
"countryCode",
"assetCode",
"amount",
"paymentAccountId",
"paymentPurpose"
]
},
"InitiateWithdrawResponse": {
"type": "object",
"properties": {
"id": {
"description": "Id of the withdraw transaction",
"type": "string",
"format": "uuid"
}
},
"required": [
"id"
]
},
"InteractionStatusParam": {
"type": "string",
"enum": [
"pending",
"approved",
"rejected",
"edited",
"submitted",
"expired",
"cancelled"
]
},
"ListAddressesParams": {
"description": "Query parameters for listing every user's addresses.",
"type": "object",
"properties": {
"username": {
"nullable": true,
"description": "Text a username must contain, matched case-insensitively, matching every username when\nomitted. A term of one or two characters must equal the whole username instead.",
"type": "string",
"pattern": "\\S",
"minLength": 1
},
"address": {
"nullable": true,
"description": "Text an address must contain, matched case-insensitively, matching every address when\nomitted. A term of one or two characters must equal the whole address instead.",
"type": "string",
"pattern": "\\S",
"minLength": 1
},
"user_id": {
"nullable": true,
"description": "Users whose addresses to return, matching any one of them, returning every user's when\nomitted.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"minItems": 1,
"maxItems": 200
},
"asset_code": {
"nullable": true,
"description": "Asset codes to return addresses for, matching any one of them, returning every asset's when\nomitted.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"vendor": {
"nullable": true,
"description": "Custody vendors to return addresses for, matching any one of them, returning every vendor's\nwhen omitted.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"vault_id": {
"nullable": true,
"description": "Vaults to return addresses for, matching any one of them, returning every vault's when\nomitted.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"sort_by": {
"$ref": "#/components/schemas/AddressSort"
},
"sort_dir": {
"description": "Direction to order the results in.",
"type": "string",
"enum": [
"asc",
"desc"
]
},
"page": {
"description": "Page number for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"page_size": {
"description": "Page size for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
}
}
},
"ListApprovalRequestsParams": {
"description": "Query parameters for listing transaction approval requests.",
"type": "object",
"properties": {
"search": {
"nullable": true,
"description": "Text the source or destination username, or the transaction ID, must contain, matched\ncase-insensitively, matching every request when omitted. A term of one or two characters\nmust equal the whole value instead.",
"type": "string",
"pattern": "\\S",
"minLength": 1
},
"tx_type": {
"nullable": true,
"description": "Transaction types to return requests for, matching any one of them, returning every type\nwhen omitted.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"source": {
"nullable": true,
"description": "Source users to return requests for, matching any one of them, returning every request\nwhen omitted.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"minItems": 1,
"maxItems": 200
},
"destination": {
"nullable": true,
"description": "Destination users to return requests for, matching any one of them, returning every request\nwhen omitted.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"minItems": 1,
"maxItems": 200
},
"asset_code": {
"nullable": true,
"description": "Asset codes (e.g. BTC) to return requests for, matching any one of them, returning every\nasset when omitted.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"status": {
"nullable": true,
"description": "Statuses to return requests in, matching any one of them, returning every status when\nomitted.",
"type": "array",
"items": {
"$ref": "#/components/schemas/ApprovalRequestStatus"
},
"minItems": 1,
"maxItems": 200
},
"completed_by": {
"nullable": true,
"description": "Usernames of the operators who completed the requests to return, matching any one of them,\nreturning every request when omitted.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"sort_by": {
"$ref": "#/components/schemas/ApprovalRequestSort"
},
"sort_dir": {
"description": "Direction to order the results in, descending when omitted.",
"type": "string",
"enum": [
"asc",
"desc"
]
},
"page": {
"description": "Page number for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"page_size": {
"description": "Page size for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
}
}
},
"ListAssetRestrictionsResponse": {
"type": "object",
"properties": {
"asset_restrictions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AssetRestrictions"
}
}
},
"required": [
"asset_restrictions"
]
},
"ListAuthUsersParams": {
"type": "object",
"properties": {
"page": {
"description": "Page number for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"page_size": {
"description": "Page size for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"include_disabled": {
"description": "When true, include disabled users in the results. Defaults to false.",
"type": "boolean"
}
},
"required": [
"page",
"page_size"
]
},
"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",
"minimum": 0,
"maximum": 4294967295
},
"page_size": {
"description": "Page size for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
}
},
"required": [
"page",
"page_size"
]
},
"ListContractParams": {
"description": "Query parameters for listing contracts.",
"type": "object",
"properties": {
"search": {
"nullable": true,
"description": "Text the contract ID must contain, matched case-insensitively, matching every contract when\nomitted. A term of one or two characters must equal the whole ID instead.",
"type": "string",
"pattern": "\\S",
"minLength": 1
},
"contract_type": {
"nullable": true,
"description": "Contract types to return, matching any one of them, returning every type when omitted.",
"type": "array",
"items": {
"$ref": "#/components/schemas/ContractType"
},
"minItems": 1,
"maxItems": 200
},
"status": {
"nullable": true,
"description": "Statuses to return contracts in, matching any one of them, returning every status when\nomitted.",
"type": "array",
"items": {
"$ref": "#/components/schemas/ContractStatus"
},
"minItems": 1,
"maxItems": 200
},
"digital_twin_only": {
"nullable": true,
"description": "Whether to return only contracts that involve only digital twins (transfers, issues and\nredeems) or only those that do not, returning both when omitted. Only `true` or `false` is\naccepted, so a blank value is a `400` rather than no filter.",
"type": "boolean"
},
"sort_by": {
"$ref": "#/components/schemas/ContractSort"
},
"sort_dir": {
"description": "Direction to order the results in, descending when omitted.",
"type": "string",
"enum": [
"asc",
"desc"
]
},
"page": {
"description": "Page number for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"page_size": {
"description": "Page size for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
}
}
},
"ListIdentitiesParams": {
"description": "Query parameters for listing user identities.",
"type": "object",
"properties": {
"search": {
"nullable": true,
"description": "Text the name, first name, last name, username or email must contain, matched\ncase-insensitively, matching every user when omitted. A term of one or two characters must\nequal the whole value instead.",
"type": "string",
"pattern": "\\S",
"minLength": 1
},
"name": {
"nullable": true,
"description": "Names to return, as first and last name joined by a space, matching any one of them\nexactly, returning every user when omitted.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"username": {
"nullable": true,
"description": "Usernames to return, matching any one of them exactly, returning every user when omitted.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"email": {
"nullable": true,
"description": "Email addresses to return, matching any one of them exactly, returning every user when\nomitted.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"phone": {
"nullable": true,
"description": "Phone numbers to return, matching any one of them exactly, returning every user when\nomitted.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"tax_id": {
"nullable": true,
"description": "Tax IDs to return, matching any one of them exactly, returning every user when omitted.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"sort_by": {
"$ref": "#/components/schemas/IdentitySort"
},
"sort_dir": {
"description": "Direction to order the results in, descending when omitted.",
"type": "string",
"enum": [
"asc",
"desc"
]
},
"page": {
"description": "Page number for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"page_size": {
"description": "Page size for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
}
}
},
"ListOrderResponse": {
"type": "object",
"properties": {
"exchange_code": {
"type": "string"
},
"order_reference": {
"type": "string"
},
"order_date": {
"type": "string"
},
"expected_settlement_date": {
"type": "string"
},
"trade_type": {
"$ref": "#/components/schemas/TradeType"
},
"user": {
"type": "string"
},
"org": {
"type": "string"
},
"status": {
"type": "string"
}
},
"required": [
"exchange_code",
"order_reference",
"order_date",
"expected_settlement_date",
"trade_type",
"user",
"org",
"status"
]
},
"ListPolicyRulesQuery": {
"description": "Query parameters for listing policy rules.",
"type": "object",
"properties": {
"include_managed": {
"nullable": true,
"description": "Include system-managed rules when true.",
"type": "boolean"
},
"order_by": {
"nullable": true,
"description": "Optional rule sort order.",
"allOf": [
{
"$ref": "#/components/schemas/RuleOrderByParam"
}
]
}
}
},
"ListReportTemplatesParams": {
"description": "Query parameters for listing report templates.",
"type": "object",
"properties": {
"search": {
"nullable": true,
"description": "Text the template name must contain, matched case-insensitively, matching every template\nwhen omitted. A term of one or two characters must equal the whole name instead.",
"type": "string",
"pattern": "\\S",
"minLength": 1
},
"root_participant": {
"nullable": true,
"description": "Root participants to return templates for, matching any one of them, returning every\ntemplate when omitted.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"minItems": 1,
"maxItems": 200
},
"id": {
"nullable": true,
"description": "Templates to return, matching any one of them, returning every template when omitted.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"minItems": 1,
"maxItems": 200
},
"sort_by": {
"$ref": "#/components/schemas/ReportTemplateSort"
},
"sort_dir": {
"description": "Direction to order the results in, descending when omitted.",
"type": "string",
"enum": [
"asc",
"desc"
]
},
"page": {
"description": "Page number for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"page_size": {
"description": "Page size for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
}
}
},
"ListSessionsQuery": {
"description": "Query parameters for listing recent sessions through the REST API.",
"type": "object",
"properties": {
"page": {
"description": "Page number for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"page_size": {
"description": "Page size for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"lookback_months": {
"nullable": true,
"description": "Maximum session age in calendar months, defaulting to four.",
"type": "integer",
"minimum": 1,
"maximum": 80000
}
},
"required": [
"page",
"page_size"
]
},
"ListTemplateResultsParams": {
"description": "Query parameters for listing a template's settlement results.",
"type": "object",
"properties": {
"period_from": {
"nullable": true,
"description": "Earliest period end to return, inclusive, in RFC3339 format; every earlier period is\nreturned too when omitted.",
"type": "string",
"format": "date-time"
},
"period_to": {
"nullable": true,
"description": "End of the period range, exclusive, in RFC3339 format; every later period is returned too\nwhen omitted.",
"type": "string",
"format": "date-time"
},
"asset_code": {
"nullable": true,
"description": "Asset codes to return values for, matching any one of them, returning every asset's when\nomitted. A period keeps its place only while it holds at least one matching value.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"applied": {
"nullable": true,
"description": "Whether to return applied or unapplied values only, returning both when omitted.",
"type": "boolean"
},
"sort_dir": {
"description": "Direction to order the periods in, latest period first when omitted.",
"type": "string",
"enum": [
"asc",
"desc"
]
},
"page": {
"description": "Page number for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"page_size": {
"description": "Page size for paginated results, counted in periods and capped at 200.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
}
}
},
"ListTransactionParams": {
"description": "Query parameters for listing contract transactions.",
"type": "object",
"properties": {
"search": {
"nullable": true,
"description": "Text the sender's or receiver's username, or the transaction ID, must contain, matched\ncase-insensitively, matching every transaction when omitted. A term of one or two characters\nmust equal the whole value instead.",
"type": "string",
"pattern": "\\S",
"minLength": 1
},
"contract_type": {
"nullable": true,
"description": "Contract types to return transactions of, matching any one of them, returning every type\nwhen omitted.",
"type": "array",
"items": {
"$ref": "#/components/schemas/ContractType"
},
"minItems": 1,
"maxItems": 200
},
"from_user_id": {
"nullable": true,
"description": "Sending users to return transactions of, matching any one of them, returning every\ntransaction when omitted.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"minItems": 1,
"maxItems": 200
},
"to_user_id": {
"nullable": true,
"description": "Receiving users to return transactions of, matching any one of them, returning every\ntransaction when omitted.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"minItems": 1,
"maxItems": 200
},
"asset_code": {
"nullable": true,
"description": "Asset codes (e.g. BTC) to return transactions of, matching any one of them, returning every\nasset when omitted.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"status": {
"nullable": true,
"description": "Contract statuses to return transactions of, matching any one of them, returning every\nstatus when omitted.",
"type": "array",
"items": {
"$ref": "#/components/schemas/ContractStatus"
},
"minItems": 1,
"maxItems": 200
},
"sort_by": {
"$ref": "#/components/schemas/ContractTransactionSort"
},
"sort_dir": {
"description": "Direction to order the results in, descending when omitted.",
"type": "string",
"enum": [
"asc",
"desc"
]
},
"page": {
"description": "Page number for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"page_size": {
"description": "Page size for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
}
}
},
"ListUsersParams": {
"description": "Query parameters for listing every user.",
"type": "object",
"properties": {
"search": {
"nullable": true,
"description": "Text a username must contain, matched case-insensitively, matching every user when omitted.\nA term of one or two characters must equal the whole username instead, so `an` finds `AN`\nbut not `Daniel`.",
"type": "string",
"pattern": "\\S",
"minLength": 1
},
"id": {
"nullable": true,
"description": "Users to return, matching any one of them, returning every user when omitted.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"minItems": 1,
"maxItems": 200
},
"verifier": {
"nullable": true,
"description": "Wallet verifiers to return the users of, matching any one of them, returning every user\nwhen omitted.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"user_type": {
"nullable": true,
"description": "Roles to return users of, matching any one of them, returning every role when omitted.",
"type": "array",
"items": {
"$ref": "#/components/schemas/UserTypeFilter"
},
"minItems": 1,
"maxItems": 200
},
"asset_code": {
"nullable": true,
"description": "Assets a returned user must hold an address in at least one of, returning every user when\nomitted.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"vendor": {
"nullable": true,
"description": "Vendors a returned user must have an identity at at least one of, returning every user when\nomitted.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"include_archived": {
"description": "Whether to list archived users alongside active ones.",
"type": "boolean"
},
"sort_by": {
"$ref": "#/components/schemas/UserSort"
},
"sort_dir": {
"description": "Direction to order the results in.",
"type": "string",
"enum": [
"asc",
"desc"
]
},
"page": {
"description": "Page number for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"page_size": {
"description": "Page size for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
}
}
},
"ListWebhookDeliveriesParams": {
"description": "Query parameters for listing webhook history.",
"type": "object",
"properties": {
"search": {
"nullable": true,
"description": "Text the target URL must contain, matched case-insensitively, matching every delivery when\nomitted. A term of one or two characters must equal the whole URL instead.",
"type": "string",
"pattern": "\\S",
"minLength": 1
},
"delivery_status": {
"nullable": true,
"description": "Delivery states to return, matching any one of them, returning every state when omitted.",
"type": "array",
"items": {
"$ref": "#/components/schemas/WebhookDeliveryStatus"
},
"minItems": 1,
"maxItems": 200
},
"subscription_id": {
"nullable": true,
"description": "Subscriptions to return deliveries to, matching any one of them, returning every\nsubscription's when omitted.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"minItems": 1,
"maxItems": 200
},
"sort_by": {
"$ref": "#/components/schemas/WebhookDeliverySort"
},
"sort_dir": {
"description": "Direction to order the results in, descending when omitted.",
"type": "string",
"enum": [
"asc",
"desc"
]
},
"page": {
"description": "Page number for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"page_size": {
"description": "Page size for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
}
}
},
"ListWebhookSubscriptionsParams": {
"description": "Query parameters for listing webhook subscriptions.",
"type": "object",
"properties": {
"search": {
"nullable": true,
"description": "Text the URL must contain, matched case-insensitively, matching every subscription when\nomitted. A term of one or two characters must equal the whole URL instead.",
"type": "string",
"pattern": "\\S",
"minLength": 1
},
"active": {
"nullable": true,
"description": "Whether to return only active or only inactive subscriptions, returning both when omitted.\nOnly `true` or `false` is accepted, so a blank value is a `400` rather than no filter.",
"type": "boolean"
},
"sort_by": {
"$ref": "#/components/schemas/WebhookSubscriptionSort"
},
"sort_dir": {
"description": "Direction to order the results in, descending when omitted.",
"type": "string",
"enum": [
"asc",
"desc"
]
},
"page": {
"description": "Page number for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"page_size": {
"description": "Page size for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
}
}
},
"ListedUserIdentity": {
"description": "A user's identity as the admin identity list reports it.",
"type": "object",
"properties": {
"user_id": {
"description": "Id of the user",
"type": "string",
"format": "uuid"
},
"username": {
"description": "Username of the user",
"type": "string"
},
"identity": {
"nullable": true,
"description": "Identity information for the user, or `null` when the stored data cannot be read as an\nidentity. Such a user is still listed, so it can be found and its identity removed.",
"allOf": [
{
"$ref": "#/components/schemas/Identity"
}
]
}
},
"required": [
"user_id",
"username"
]
},
"McpToolAccessPrecheckRequest": {
"description": "Request to precheck whether a user may call an MCP tool.",
"type": "object",
"properties": {
"tool_name": {
"description": "MCP tool name to check.",
"type": "string"
}
},
"required": [
"tool_name"
]
},
"McpToolAccessPrecheckResponse": {
"description": "Result of an MCP tool access precheck.",
"type": "object",
"properties": {
"tool_name": {
"description": "MCP tool name that was checked.",
"type": "string"
},
"allowed": {
"description": "Whether the current user may call the tool.",
"type": "boolean"
},
"required_permission": {
"nullable": true,
"description": "Permission required for the tool, when known.",
"type": "string"
},
"deny_reason": {
"nullable": true,
"description": "Denial reason when access is not allowed.",
"type": "string"
}
},
"required": [
"tool_name",
"allowed"
]
},
"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",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
},
"fee_level": {
"$ref": "#/components/schemas/FeeLevel"
},
"memo": {
"nullable": true,
"description": "Optional memo to attach to transaction.",
"type": "string"
},
"vendor": {
"nullable": true,
"description": "Optional backend vendor, defaults to default custody vendor",
"allOf": [
{
"$ref": "#/components/schemas/CustodyVendor"
}
]
}
},
"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": {
"nullable": true,
"description": "The mobile money network provider. This field is deprecated, please use networkSlug instead as the list of supported operators can dynamically change.",
"allOf": [
{
"$ref": "#/components/schemas/MobileMoneyProvider"
}
]
},
"recipientRelationship": {
"nullable": true,
"description": "The relationship between the sender and the recipient. Required by some payment providers.",
"allOf": [
{
"$ref": "#/components/schemas/RecipientRelationship"
}
]
}
},
"required": [
"phone",
"accountHolderName"
]
},
"MobileMoneyDetailsEntity": {
"type": "object",
"properties": {
"accountHolderName": {
"type": "string"
},
"phone": {
"type": "string"
},
"networkProvider": {
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/MobileMoneyProvider"
}
]
},
"networkSlug": {
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/MobileMoneyProvider"
}
]
}
},
"required": [
"accountHolderName",
"phone"
]
},
"MobileMoneyProvider": {
"type": "string",
"enum": [
"AIRTEL",
"BKTRX",
"FAWRY",
"CHECKOUT",
"CRDTRX",
"EXPRESSO",
"FLOOZ",
"FREE",
"HALOPESA",
"MOBICASH",
"MOOV",
"MPESA",
"MTN",
"MYZAKA",
"OPAY",
"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",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
},
"gas_price": {
"nullable": true,
"description": "for evm based networks",
"type": "string",
"format": "decimal",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
},
"network_fee": {
"nullable": true,
"description": "fee for non-evm and non-utxo based networks",
"type": "string",
"format": "decimal",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
},
"base_fee": {
"nullable": true,
"description": "eth assets",
"type": "string",
"format": "decimal",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
},
"priority_fee": {
"nullable": true,
"description": "eth assets",
"type": "string",
"format": "decimal",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
}
}
},
"NetworkId": {
"type": "string",
"enum": [
"POLYGON",
"ETHEREUM",
"TRON",
"BASE",
"OPTIMISM",
"BITCOIN",
"SOLANA",
"CELO"
]
},
"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"
]
},
"OnchainDetailsCreateDto": {
"type": "object",
"properties": {
"onchainNetwork": {
"$ref": "#/components/schemas/NetworkId"
},
"onchainAddress": {
"description": "The blockchain address that receives the funds.",
"type": "string"
}
},
"required": [
"onchainNetwork",
"onchainAddress"
]
},
"OnchainDetailsEntity": {
"type": "object",
"properties": {
"onchainNetwork": {
"$ref": "#/components/schemas/NetworkId"
},
"onchainAddress": {
"description": "The blockchain address that receives the funds.",
"type": "string"
}
},
"required": [
"onchainNetwork",
"onchainAddress"
]
},
"OnchainTransaction": {
"type": "object",
"properties": {
"to": {
"nullable": true,
"description": "Address receiving the assets",
"allOf": [
{
"$ref": "#/components/schemas/Address"
}
]
},
"from": {
"nullable": true,
"description": "Address sending the assets",
"allOf": [
{
"$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",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
},
"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",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
},
"fee_level": {
"nullable": true,
"description": "Fee level used for the transaction",
"allOf": [
{
"$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"
]
},
"OrderResponse": {
"type": "object",
"properties": {
"blockchain": {
"type": "string"
},
"exchange_code": {
"type": "string"
},
"expected_settlement_date": {
"type": "string"
},
"gross_value": {
"type": "string"
},
"net_value": {
"type": "string"
},
"network_fee": {
"type": "string"
},
"order_date": {
"type": "string"
},
"order_reference": {
"type": "string"
},
"org": {
"type": "string"
},
"quantity": {
"type": "number"
},
"rate": {
"nullable": true,
"type": "string"
},
"settlement_currency": {
"type": "string"
},
"settlement_wallet_address": {
"type": "string"
},
"status": {
"type": "string"
},
"token_contract_address": {
"type": "string"
},
"trade_type": {
"$ref": "#/components/schemas/TradeType"
},
"transaction_fee": {
"type": "string"
},
"user": {
"type": "string"
},
"deposit_wallet_address": {
"type": "string"
}
},
"required": [
"blockchain",
"exchange_code",
"expected_settlement_date",
"gross_value",
"net_value",
"network_fee",
"order_date",
"order_reference",
"org",
"quantity",
"settlement_currency",
"settlement_wallet_address",
"status",
"token_contract_address",
"trade_type",
"transaction_fee",
"user",
"deposit_wallet_address"
]
},
"OrderStatusResponse": {
"type": "object",
"properties": {
"status": {
"type": "string"
},
"next_status": {
"type": "string"
}
},
"required": [
"status",
"next_status"
]
},
"PaginationParams": {
"description": "Pagination parameters shared by every paged list endpoint and database query.\n\nDeserialized directly from request query strings via `axum::extract::Query`, and\npassed into paged database functions so the persistence layer accepts one canonical\npagination shape rather than a loose pair of integers.",
"type": "object",
"properties": {
"page": {
"description": "Page number for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"page_size": {
"description": "Page size for paginated results.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
}
},
"required": [
"page",
"page_size"
]
},
"PaymentAccount": {
"description": "A payment account for a user, tagged by vendor.",
"type": "object",
"properties": {
"type": {
"example": "vendor_a",
"description": "Vendor integration the payment account belongs to.",
"type": "string"
},
"data": {
"description": "Vendor-specific payment account details, as JSON.",
"type": "object"
}
},
"required": [
"type",
"data"
]
},
"PaymentInstructionCreateDto": {
"type": "object",
"properties": {
"country": {
"nullable": true,
"description": "The country code in ISO-3166-2 format where the payment instructions are applied. See [ISO-3166-2 documentation](https://www.iso.org/iso-3166-country-codes.html). Not applicable when `paymentMethod` is `Onchain`.",
"allOf": [
{
"$ref": "#/components/schemas/CountryCode"
}
]
},
"currency": {
"nullable": true,
"description": "The fiat currency for the payment instructions. Not applicable when `paymentMethod` is `Onchain` — the token is set in `details.asset` instead.",
"allOf": [
{
"$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": [
"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"
},
"recipientRelationship": {
"nullable": true,
"description": "The relationship between the sender and the recipient. Required by some payment providers.",
"allOf": [
{
"$ref": "#/components/schemas/RecipientRelationship"
}
]
},
"address": {
"nullable": true,
"description": "Beneficiary bank address. Optional; required only for certain countries/corridors. The beneficiary's own address is taken from the identity.",
"allOf": [
{
"$ref": "#/components/schemas/PostalAddressCreateDto"
}
]
}
},
"required": [
"accountHolderName",
"bankAccountNumber",
"bankRoutingNumber",
"bankAccountType"
]
},
{
"type": "object",
"properties": {
"bankSlug": {
"nullable": true,
"description": "The bank code for the account, such as a routing number or sort code",
"type": "string"
},
"bankAccountNumber": {
"nullable": true,
"description": "The bank account number",
"type": "string"
},
"localRoutingCode": {
"nullable": true,
"description": "Required for the following payment methods: BECS,FPS,IMPS_FIRC,EFT,TED. It may contain country-specific bank or branch identifiers such as branch code, transit number, BSB, IFSC, clearing code, or similar local routing codes.",
"type": "string"
},
"branchCode": {
"nullable": true,
"description": "A secondary local routing identifier used when a rail requires two codes, such as the branch code for JPY bank transfers or the transit number for CAD EFT.",
"type": "string"
},
"bankName": {
"nullable": true,
"description": "The name of the bank.",
"type": "string"
},
"swiftOrBicNumber": {
"nullable": true,
"description": "Beneficiary bank swift or bic number. Required for some regions",
"type": "string"
},
"accountHolderName": {
"nullable": true,
"description": "The name of the account holder. Required for Colombia.",
"type": "string"
},
"bankAccountType": {
"nullable": true,
"description": "The type of bank account.",
"allOf": [
{
"$ref": "#/components/schemas/BankAccountType"
}
]
},
"bankAccountNumberType": {
"nullable": true,
"description": "The type of bank account number. Required for Argentina.",
"allOf": [
{
"$ref": "#/components/schemas/BankAccountNumberType"
}
]
},
"address": {
"nullable": true,
"description": "Beneficiary bank address. Optional; required only for certain countries/corridors. The beneficiary's own address is taken from the identity.",
"allOf": [
{
"$ref": "#/components/schemas/PostalAddressCreateDto"
}
]
},
"recipientRelationship": {
"nullable": true,
"description": "The relationship between the sender and the recipient. Required by some payment providers.",
"allOf": [
{
"$ref": "#/components/schemas/RecipientRelationship"
}
]
},
"bankCode": {
"nullable": true,
"description": "DEPRECATED. The bank code for the account, such as a routing number or sort code.",
"type": "string"
},
"phone": {
"nullable": true,
"description": "DEPRECATED. The phone number associated with the bank account.",
"type": "string"
},
"taxId": {
"nullable": true,
"description": "DEPRECATED. The tax identification number associated with the account.",
"type": "string"
}
}
},
{
"type": "object",
"properties": {
"bankSlug": {
"nullable": true,
"description": "The bank code for the account, such as a routing number or sort code",
"type": "string"
},
"localRoutingCode": {
"nullable": true,
"description": "Country-specific bank or branch identifier. Required by corridors whose IBAN alone does not identify the bank, such as Denmark and Norway.",
"type": "string"
},
"swiftOrBicNumber": {
"nullable": true,
"description": "Beneficiary bank swift or bic number. Required by corridors that pair an IBAN with a SWIFT code, such as the UAE and Poland.",
"type": "string"
},
"iban": {
"nullable": true,
"description": "The bank account number",
"type": "string"
},
"bankAccountNumber": {
"nullable": true,
"description": "The domestic account number behind the IBAN. Required by corridors that ask for both, such as Norway.",
"type": "string"
},
"bankName": {
"nullable": true,
"description": "The name of the bank. Required by PFIs that identify the institution by name rather than by code — payouts without it may be rejected.",
"type": "string"
},
"address": {
"nullable": true,
"description": "Beneficiary bank address. Optional; required only for certain countries/corridors. The beneficiary's own address is taken from the identity.",
"allOf": [
{
"$ref": "#/components/schemas/PostalAddressCreateDto"
}
]
}
}
},
{
"type": "object",
"properties": {
"identifierType": {
"$ref": "#/components/schemas/PaymentInstructionIdentifierType"
},
"identifierValue": {
"description": "The value of the identifier, such as a PIX key or similar",
"type": "string"
},
"address": {
"nullable": true,
"description": "The address is deprecated in Identifier Payment Instruction and will be removed in future releases.",
"allOf": [
{
"$ref": "#/components/schemas/PostalAddressCreateDto"
}
]
}
},
"required": [
"identifierType",
"identifierValue"
]
},
{
"type": "object",
"properties": {
"brebKey": {
"description": "The Bre-B key value registered for the recipient.",
"type": "string"
}
},
"required": [
"brebKey"
]
},
{
"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": {
"nullable": true,
"description": "Beneficiary bank address. Optional; required only for certain countries/corridors. The beneficiary's own address is taken from the identity.",
"allOf": [
{
"$ref": "#/components/schemas/PostalAddressCreateDto"
}
]
}
},
"required": [
"accountHolderName",
"bankAccountNumber",
"swiftOrBicNumber",
"accountOwnerType"
]
},
{
"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": {
"nullable": true,
"description": "The mobile money network provider. This field is deprecated, please use networkSlug instead as the list of supported operators can dynamically change.",
"allOf": [
{
"$ref": "#/components/schemas/MobileMoneyProvider"
}
]
},
"recipientRelationship": {
"nullable": true,
"description": "The relationship between the sender and the recipient. Required by some payment providers.",
"allOf": [
{
"$ref": "#/components/schemas/RecipientRelationship"
}
]
}
},
"required": [
"phone",
"accountHolderName"
]
},
{
"type": "object",
"properties": {
"iban": {
"description": "UK IBAN. Required: UK FPS payouts cannot be created without it, and the sort code and account number are derived from it.",
"type": "string"
},
"localRoutingCode": {
"nullable": true,
"description": "UK sort code (6 digits, hyphens optional). Optional — auto-derived from the IBAN. If provided, must match the IBAN.",
"type": "string"
},
"bankAccountNumber": {
"nullable": true,
"description": "UK bank account number (8 digits). Optional — auto-derived from the IBAN. If provided, must match the IBAN.",
"type": "string"
},
"bankName": {
"nullable": true,
"description": "Bank name, e.g. Barclays.",
"type": "string"
},
"bankSlug": {
"nullable": true,
"description": "Anonymized bank slug returned by the institutions list endpoint.",
"type": "string"
},
"bankAccountType": {
"nullable": true,
"description": "Account type (Checking or Savings).",
"allOf": [
{
"$ref": "#/components/schemas/BankAccountType"
}
]
},
"address": {
"nullable": true,
"description": "Beneficiary bank address. Optional; required only for certain countries/corridors. The beneficiary's own address is taken from the identity.",
"allOf": [
{
"$ref": "#/components/schemas/PostalAddressCreateDto"
}
]
}
},
"required": [
"iban"
]
},
{
"type": "object",
"properties": {
"onchainNetwork": {
"$ref": "#/components/schemas/NetworkId"
},
"onchainAddress": {
"description": "The blockchain address that receives the funds.",
"type": "string"
}
},
"required": [
"onchainNetwork",
"onchainAddress"
]
}
]
},
"PaymentInstructionEntity": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"identityId": {
"type": "string"
},
"name": {
"type": "string"
},
"paymentMethod": {
"$ref": "#/components/schemas/PaymentMethod"
},
"currency": {
"nullable": true,
"type": "string"
},
"country": {
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/CountryCode"
}
]
},
"deleted": {
"type": "boolean"
},
"createdAt": {
"type": "string"
},
"details": {
"$ref": "#/components/schemas/PaymentInstructionEntityDetails"
}
},
"required": [
"id",
"identityId",
"name",
"paymentMethod",
"deleted",
"createdAt",
"details"
]
},
"PaymentInstructionEntityDetails": {
"oneOf": [
{
"type": "object",
"properties": {
"bankName": {
"nullable": true,
"type": "string"
},
"accountHolderName": {
"type": "string"
},
"bankAccountNumber": {
"nullable": true,
"description": "Full bank account number (PII). Nullable / omitted by default. Returned only when your organization has been granted access to full payment-instruction details. Contact support to enable.",
"type": "string"
},
"bankAccountNumberLast4": {
"type": "string"
},
"bankRoutingNumber": {
"type": "string"
},
"bankAccountType": {
"$ref": "#/components/schemas/BankAccountType"
},
"recipientRelationship": {
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/RecipientRelationship"
}
]
},
"address": {
"nullable": true,
"description": "Beneficiary bank address. The beneficiary's own address is taken from the identity.",
"allOf": [
{
"$ref": "#/components/schemas/PostalAddressEntity"
}
]
},
"bankSlug": {
"nullable": true,
"type": "string"
},
"bankCode": {
"nullable": true,
"type": "string"
},
"phone": {
"nullable": true,
"type": "string"
},
"taxId": {
"nullable": true,
"type": "string"
}
},
"required": [
"accountHolderName",
"bankAccountNumberLast4",
"bankRoutingNumber",
"bankAccountType"
]
},
{
"type": "object",
"properties": {
"bankSlug": {
"nullable": true,
"type": "string"
},
"iban": {
"nullable": true,
"description": "Full IBAN (PII). Nullable / omitted by default. Returned only when your organization has been granted access to full payment-instruction details. Contact support to enable.",
"type": "string"
},
"ibanLast4": {
"type": "string"
},
"localRoutingCode": {
"nullable": true,
"type": "string"
},
"swiftOrBicNumber": {
"nullable": true,
"type": "string"
},
"address": {
"nullable": true,
"description": "Beneficiary bank address.",
"allOf": [
{
"$ref": "#/components/schemas/PostalAddressEntity"
}
]
},
"bankAccountNumberLast4": {
"type": "string"
},
"bankName": {
"nullable": true,
"type": "string"
},
"bankRoutingNumber": {
"nullable": true,
"type": "string"
},
"bankCode": {
"nullable": true,
"type": "string"
},
"accountHolderName": {
"nullable": true,
"type": "string"
},
"bankAccountType": {
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/BankAccountType"
}
]
},
"recipientRelationship": {
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/RecipientRelationship"
}
]
},
"phone": {
"nullable": true,
"type": "string"
},
"taxId": {
"nullable": true,
"type": "string"
}
},
"required": [
"ibanLast4",
"bankAccountNumberLast4"
]
},
{
"type": "object",
"properties": {
"bankName": {
"nullable": true,
"type": "string"
},
"bankSlug": {
"nullable": true,
"type": "string"
},
"bankAccountNumber": {
"nullable": true,
"description": "Full bank account number (PII). Nullable / omitted by default. Returned only when your organization has been granted access to full payment-instruction details. Contact support to enable.",
"type": "string"
},
"bankAccountNumberLast4": {
"type": "string"
},
"localRoutingCode": {
"nullable": true,
"type": "string"
},
"branchCode": {
"nullable": true,
"type": "string"
},
"swiftOrBicNumber": {
"nullable": true,
"type": "string"
},
"accountHolderName": {
"nullable": true,
"type": "string"
},
"bankAccountType": {
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/BankAccountType"
}
]
},
"bankAccountNumberType": {
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/BankAccountNumberType"
}
]
},
"address": {
"nullable": true,
"description": "Beneficiary bank address. The beneficiary's own address is taken from the identity.",
"allOf": [
{
"$ref": "#/components/schemas/PostalAddressEntity"
}
]
},
"bankRoutingNumber": {
"nullable": true,
"type": "string"
},
"bankCode": {
"nullable": true,
"type": "string"
},
"phone": {
"nullable": true,
"type": "string"
},
"taxId": {
"nullable": true,
"type": "string"
},
"recipientRelationship": {
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/RecipientRelationship"
}
]
}
},
"required": [
"bankAccountNumberLast4"
]
},
{
"type": "object",
"properties": {
"identifierType": {
"$ref": "#/components/schemas/PaymentInstructionIdentifierType"
},
"identifierValue": {
"type": "string"
},
"address": {
"nullable": true,
"description": "The address associated with the Identifier Payment Instruction is deprecated.",
"allOf": [
{
"$ref": "#/components/schemas/PostalAddressEntity"
}
]
}
},
"required": [
"identifierType",
"identifierValue"
]
},
{
"type": "object",
"properties": {
"brebKey": {
"description": "The Bre-B key value registered for the recipient.",
"type": "string"
}
},
"required": [
"brebKey"
]
},
{
"type": "object",
"properties": {
"bankName": {
"type": "string"
},
"bankAccountNumber": {
"nullable": true,
"description": "Full bank account number (PII). Nullable / omitted by default. Returned only when your organization has been granted access to full payment-instruction details. Contact support to enable.",
"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": {
"nullable": true,
"description": "Beneficiary bank address. The beneficiary's own address is taken from the identity.",
"allOf": [
{
"$ref": "#/components/schemas/PostalAddressEntity"
}
]
}
},
"required": [
"bankName",
"bankAccountNumberLast4",
"accountHolderName",
"swiftOrBicNumber",
"accountOwnerType"
]
},
{
"type": "object",
"properties": {
"accountHolderName": {
"type": "string"
},
"bankAccountNumber": {
"nullable": true,
"description": "Full bank account number (PII). Nullable / omitted by default. Returned only when your organization has been granted access to full payment-instruction details. Contact support to enable.",
"type": "string"
},
"iban": {
"nullable": true,
"description": "Full IBAN (PII). Nullable / omitted by default. Returned only when your organization has been granted access to full payment-instruction details. Contact support to enable.",
"type": "string"
},
"bankAccountNumberLast4": {
"nullable": true,
"type": "string"
},
"swiftOrBicNumber": {
"nullable": true,
"type": "string"
},
"ibanLast4": {
"nullable": true,
"type": "string"
},
"address": {
"nullable": true,
"description": "Beneficiary bank address. Optional; required for SWIFT payouts. The beneficiary's own address is taken from the identity.",
"allOf": [
{
"$ref": "#/components/schemas/PostalAddressEntity"
}
]
},
"bankSlug": {
"nullable": true,
"type": "string"
},
"bankName": {
"nullable": true,
"type": "string"
},
"bankAccountType": {
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/BankAccountType"
}
]
},
"intermediaryBankName": {
"nullable": true,
"type": "string"
},
"intermediaryBankSwiftOrBicNumber": {
"nullable": true,
"type": "string"
},
"intermediaryBankRoutingNumber": {
"nullable": true,
"type": "string"
},
"intermediaryBankAddress": {
"nullable": true,
"type": "string"
},
"beneficiaryBankCnapsCode": {
"nullable": true,
"type": "string"
},
"beneficiaryPhone": {
"nullable": true,
"type": "string"
},
"beneficiaryAddressInChinese": {
"nullable": true,
"type": "string"
},
"recipientRelationship": {
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/RecipientRelationship"
}
]
},
"bankAddress": {
"nullable": true,
"description": "Deprecated. Use the structured `address` field for the beneficiary bank address.",
"type": "string"
}
},
"required": [
"accountHolderName"
]
},
{
"type": "object",
"properties": {
"accountHolderName": {
"type": "string"
},
"phone": {
"type": "string"
},
"networkProvider": {
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/MobileMoneyProvider"
}
]
},
"networkSlug": {
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/MobileMoneyProvider"
}
]
}
},
"required": [
"accountHolderName",
"phone"
]
},
{
"type": "object",
"properties": {
"bankName": {
"nullable": true,
"type": "string"
},
"bankSlug": {
"nullable": true,
"type": "string"
},
"bankAccountNumber": {
"nullable": true,
"description": "Full bank account number (PII). Nullable / omitted by default. Returned only when your organization has been granted access to full payment-instruction details. Contact support to enable.",
"type": "string"
},
"bankAccountNumberLast4": {
"nullable": true,
"type": "string"
},
"sortCode": {
"nullable": true,
"description": "6-digit UK sort code (derived from IBAN positions 9-14).",
"type": "string"
},
"iban": {
"nullable": true,
"description": "Full IBAN (PII). Nullable / omitted by default. Returned only when your organization has been granted access to full payment-instruction details. Contact support to enable.",
"type": "string"
},
"ibanLast4": {
"nullable": true,
"type": "string"
},
"accountHolderName": {
"nullable": true,
"type": "string"
},
"bankAccountType": {
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/BankAccountType"
}
]
},
"address": {
"nullable": true,
"description": "Beneficiary bank address. The beneficiary's own address is taken from the identity.",
"allOf": [
{
"$ref": "#/components/schemas/PostalAddressEntity"
}
]
}
}
},
{
"type": "object",
"properties": {
"onchainNetwork": {
"$ref": "#/components/schemas/NetworkId"
},
"onchainAddress": {
"description": "The blockchain address that receives the funds.",
"type": "string"
}
},
"required": [
"onchainNetwork",
"onchainAddress"
]
}
]
},
"PaymentInstructionIdentifierType": {
"type": "string",
"enum": [
"PhoneNumber",
"Email",
"CPF",
"EVP",
"CNPJ",
"UPI"
]
},
"PaymentMethod": {
"type": "string",
"enum": [
"ACH",
"Wire",
"Sepa",
"Swift",
"Card",
"MobileMoney",
"PIX",
"TED",
"PSE",
"SPEI",
"COELSA",
"Transfers30",
"SPAV",
"TEF",
"CCE",
"SPI",
"LBTR",
"SINPE",
"Transfer365",
"NIP",
"GhIPSS",
"BankTransfer",
"EFT",
"RTP",
"BECS",
"FPS",
"IMPS_FIRC",
"Breb",
"NPSS",
"MADA",
"ZAHAV",
"IBFT",
"SIC",
"Alipay",
"Tips",
"Napas",
"BiFast",
"FastSg",
"Instapay",
"Ipp",
"Giro",
"Elixir",
"FastRtp",
"TransFond",
"Nics",
"Cnaps",
"UnionPay",
"UPI",
"Onchain"
]
},
"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"
]
},
"PendingDecisionsQuery": {
"description": "Query parameters for pending policy decisions.",
"type": "object",
"properties": {
"session_id": {
"description": "Session whose pending decisions should be listed.",
"type": "string",
"format": "uuid"
}
},
"required": [
"session_id"
]
},
"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"
]
},
"PolicyAuditEventResponse": {
"description": "Policy audit event returned by the MCP policy audit API.",
"type": "object",
"properties": {
"id": {
"description": "Unique audit event id.",
"type": "string",
"format": "uuid"
},
"event_type": {
"description": "Audit event type.",
"type": "string"
},
"kc_user_id": {
"nullable": true,
"description": "Keycloak user associated with the event, when available.",
"type": "string",
"format": "uuid"
},
"agent_id": {
"nullable": true,
"description": "Agent associated with the event, when available.",
"type": "string",
"format": "uuid"
},
"session_id": {
"nullable": true,
"description": "Session associated with the event, when available.",
"type": "string",
"format": "uuid"
},
"decision_id": {
"nullable": true,
"description": "Policy decision associated with the event, when available.",
"type": "string",
"format": "uuid"
},
"rule_id": {
"nullable": true,
"description": "Policy rule associated with the event, when available.",
"type": "string",
"format": "uuid"
},
"payload_json": {
"description": "Event-specific JSON payload.",
"type": "object"
},
"created": {
"description": "Event creation timestamp.",
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"event_type",
"payload_json",
"created"
]
},
"PolicyDecisionOutcomeParam": {
"type": "string",
"enum": [
"allow",
"deny",
"require_approval",
"require_input"
]
},
"PolicyDecisionResponse": {
"description": "Policy decision returned by the MCP policy decision API.",
"type": "object",
"properties": {
"id": {
"description": "Unique decision id.",
"type": "string",
"format": "uuid"
},
"session_id": {
"description": "Session associated with the decision.",
"type": "string",
"format": "uuid"
},
"kc_user_id": {
"nullable": true,
"description": "Keycloak user associated with the decision, when available.",
"type": "string",
"format": "uuid"
},
"evaluation_context_json": {
"description": "JSON context evaluated by the policy engine.",
"type": "object"
},
"decision_outcome": {
"description": "Policy outcome value, such as `allow` or `require_input`.",
"type": "string"
},
"reason": {
"description": "Human-readable reason for the decision.",
"type": "string"
},
"rule_id": {
"nullable": true,
"description": "Matching policy rule id, when a rule matched.",
"type": "string",
"format": "uuid"
},
"required_interaction_json": {
"nullable": true,
"description": "Interaction request payload required to continue, when applicable.",
"type": "object"
},
"status": {
"description": "Current interaction status.",
"type": "string"
},
"response_json": {
"nullable": true,
"description": "Submitted response payload, when resolved.",
"type": "object"
},
"created": {
"description": "Decision creation timestamp.",
"type": "string",
"format": "date-time"
},
"resolved": {
"nullable": true,
"description": "Decision resolution timestamp, when resolved.",
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"session_id",
"evaluation_context_json",
"decision_outcome",
"reason",
"status",
"created"
]
},
"PolicyRuleResponse": {
"description": "Policy rule returned by the MCP policy rule API.",
"type": "object",
"properties": {
"id": {
"description": "Unique policy rule id.",
"type": "string",
"format": "uuid"
},
"name": {
"description": "Human-readable rule name.",
"type": "string"
},
"description": {
"nullable": true,
"description": "Optional rule description.",
"type": "string"
},
"priority": {
"description": "Rule priority; higher-priority rules are evaluated first.",
"type": "integer",
"format": "int32",
"minimum": -2147483648,
"maximum": 2147483647
},
"condition_json": {
"description": "JSON condition matched against tool evaluation context.",
"type": "object"
},
"outcome_json": {
"description": "JSON policy outcome applied when the condition matches.",
"type": "object"
},
"reason": {
"description": "Human-readable reason recorded with matching decisions.",
"type": "string"
},
"managed": {
"description": "Whether the rule is system-managed.",
"type": "boolean"
},
"created": {
"description": "Rule creation timestamp.",
"type": "string",
"format": "date-time"
},
"updated": {
"description": "Last rule update timestamp.",
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"name",
"priority",
"condition_json",
"outcome_json",
"reason",
"managed",
"created",
"updated"
]
},
"PostalAddressCreateDto": {
"description": "A postal address.",
"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",
"type": "string"
},
"country": {
"description": "The country code",
"type": "string"
},
"postalCode": {
"nullable": true,
"description": "The postal code",
"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"
]
},
"QuoteStatus": {
"type": "object",
"properties": {
"timestamp": {
"type": "string"
},
"error_code": {
"type": "integer",
"format": "int64",
"minimum": -9223372036854775808,
"maximum": 9223372036854775807
},
"error_message": {
"nullable": true,
"type": "string"
},
"elapsed": {
"type": "integer",
"format": "int64",
"minimum": -9223372036854775808,
"maximum": 9223372036854775807
},
"credit_count": {
"type": "integer",
"format": "int64",
"minimum": -9223372036854775808,
"maximum": 9223372036854775807
},
"notice": {
"nullable": true,
"type": "string"
}
},
"required": [
"timestamp",
"error_code",
"elapsed",
"credit_count"
]
},
"QuotesSuccessResponse": {
"type": "object",
"properties": {
"asset_code": {
"type": "string"
},
"usd_rate": {
"type": "string"
}
},
"required": [
"asset_code",
"usd_rate"
]
},
"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"
]
},
"RecentSessionResponse": {
"description": "Summary of a recent MCP session returned by the list-sessions endpoint.",
"type": "object",
"properties": {
"session_id": {
"description": "Unique identifier of the session.",
"type": "string",
"format": "uuid"
},
"title": {
"nullable": true,
"description": "Optional human-readable title assigned to the session.",
"type": "string"
},
"started_at": {
"description": "Timestamp when the session was created.",
"type": "string",
"format": "date-time"
},
"last_message_at": {
"description": "Timestamp of the most recent message in the session.",
"type": "string",
"format": "date-time"
},
"status": {
"$ref": "#/components/schemas/SessionStatusResponse"
}
},
"required": [
"session_id",
"started_at",
"last_message_at",
"status"
]
},
"RecipientRelationship": {
"type": "string",
"enum": [
"first party",
"employee",
"independent contractor",
"vendor or supplier",
"subsidiary or affiliate",
"merchant or partner",
"customer",
"landlord",
"family",
"other"
]
},
"RegisterTreasuryUserRequest": {
"type": "object",
"properties": {
"vault_id": {
"description": "Vault ID of the custody vendor to associate with the user",
"type": "string"
},
"vendor": {
"nullable": true,
"description": "Custody vendor for the vault",
"allOf": [
{
"$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"
]
},
"RemoveRolesRequest": {
"type": "object",
"properties": {
"roles": {
"description": "The names of the realm-level roles to remove.",
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"roles"
]
},
"ReportEntry": {
"type": "object",
"properties": {
"asset_code": {
"description": "Asset code (e.g. BTC)",
"type": "string"
},
"amount": {
"description": "Amount of the asset",
"type": "string",
"format": "decimal",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
},
"period_start": {
"description": "Start of the reporting period in RFC3339 format",
"type": "string",
"format": "date-time"
},
"period_end": {
"description": "End of the reporting period in RFC3339 format",
"type": "string",
"format": "date-time"
},
"commitments": {
"description": "Number of commitments included in this entry",
"type": "integer",
"format": "int64",
"minimum": -9223372036854775808,
"maximum": 9223372036854775807
},
"applied_at": {
"nullable": true,
"description": "Timestamp when the report template was applied in RFC3339 format",
"type": "string",
"format": "date-time"
}
},
"required": [
"asset_code",
"amount",
"period_start",
"period_end",
"commitments"
]
},
"ReportItem": {
"type": "object",
"properties": {
"id": {
"description": "ID of the report",
"type": "string",
"format": "uuid"
},
"template_id": {
"description": "ID of the template used to generate this report",
"type": "string",
"format": "uuid"
},
"period_end": {
"description": "Timestamp of the end of the period this report covers",
"type": "string",
"format": "date-time"
},
"status": {
"$ref": "#/components/schemas/ReportStatus"
}
},
"required": [
"id",
"template_id",
"period_end",
"status"
]
},
"ReportStatus": {
"type": "string",
"enum": [
"UNAPPLIED",
"APPLIED",
"SUPERSEDED"
]
},
"ReportTemplate": {
"type": "object",
"properties": {
"id": {
"description": "ID of the report template",
"type": "string",
"format": "uuid"
},
"name": {
"description": "Name of the report template",
"type": "string"
},
"root_participant": {
"description": "User ID of the participant that all settlements must include as either a sender or recipient",
"type": "string",
"format": "uuid"
},
"counterparties": {
"description": "User IDs of counterparties that are included (if inclusive) or excluded (if not inclusive)",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"inclusive": {
"description": "Whether the counterparties are inclusive or exclusive",
"type": "boolean"
},
"period_start": {
"nullable": true,
"description": "The earliest `period_start` across all report results for this template.\nThis may be `None` when the most recent applied or unapplied run was empty.",
"type": "string",
"format": "date-time"
},
"applied_period_end": {
"nullable": true,
"description": "The `period_end` of the most recent applied report run for this template.\nThis may be populated even when `period_start` is `None` if that run was empty.",
"type": "string",
"format": "date-time"
},
"unapplied_period_end": {
"nullable": true,
"description": "The `period_end` of the most recent unapplied report run for this template.\nThis may be populated even when `period_start` is `None` if that run was empty.",
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"name",
"root_participant",
"counterparties",
"inclusive"
]
},
"ReportTemplateSort": {
"type": "string",
"enum": [
"created",
"name",
"participant",
"period_start",
"period_end"
]
},
"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"
]
},
"ResolveUserParams": {
"description": "Query parameters for resolving a human-supplied user reference.",
"type": "object",
"properties": {
"query": {
"description": "User id, username, or text in a username to resolve. A match at the start of the name\nbeats one at the start of a later word, which beats one anywhere else in it. A reference of\none or two characters must equal the whole username instead.",
"type": "string",
"pattern": "\\S",
"minLength": 1
},
"limit": {
"nullable": true,
"description": "Maximum number of candidates to return when the reference is ambiguous.",
"type": "integer",
"format": "int64",
"minimum": -9223372036854775808,
"maximum": 9223372036854775807
},
"user_type": {
"nullable": true,
"description": "Roles a resolved user must hold one of, resolving among every role when omitted.",
"type": "array",
"items": {
"$ref": "#/components/schemas/UserTypeFilter"
},
"minItems": 1,
"maxItems": 200
}
},
"required": [
"query"
]
},
"ResolveUserResponse": {
"description": "Outcome of resolving a user reference, either a single user or the choices to pick between.",
"type": "object",
"properties": {
"user": {
"nullable": true,
"description": "The user the reference resolved to, set only when the match was unambiguous.",
"allOf": [
{
"$ref": "#/components/schemas/ResolvedUser"
}
]
},
"candidates": {
"description": "Users tied at the strongest rank found, for the caller to choose between; empty unless the\nreference was ambiguous.",
"type": "array",
"items": {
"$ref": "#/components/schemas/ResolvedUser"
}
}
},
"required": [
"candidates"
]
},
"ResolvedUser": {
"description": "A user that matched a resolution query.",
"type": "object",
"properties": {
"id": {
"description": "ID of the user",
"type": "string",
"format": "uuid"
},
"username": {
"description": "Username of the user",
"type": "string"
},
"verifier": {
"description": "Wallet verifier of the user",
"type": "string"
},
"user_type": {
"description": "Type of the user",
"type": "string"
}
},
"required": [
"id",
"username",
"verifier",
"user_type"
]
},
"Role": {
"type": "string",
"enum": [
"admin",
"api-key",
"checker",
"maker"
]
},
"RuleOrderByParam": {
"type": "string",
"enum": [
"priority_desc",
"updated_at_desc"
]
},
"RunReportRequest": {
"type": "object",
"properties": {
"period_end": {
"description": "End time of the report period in RFC3339 format",
"type": "string",
"format": "date-time"
}
},
"required": [
"period_end"
]
},
"RunReportResponse": {
"type": "object",
"properties": {
"id": {
"description": "ID of the generated report",
"type": "string",
"format": "uuid"
}
},
"required": [
"id"
]
},
"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": {
"nullable": true,
"description": "Beneficiary bank address. Optional; required only for certain countries/corridors. The beneficiary's own address is taken from the identity.",
"allOf": [
{
"$ref": "#/components/schemas/PostalAddressCreateDto"
}
]
}
},
"required": [
"accountHolderName",
"bankAccountNumber",
"swiftOrBicNumber",
"accountOwnerType"
]
},
"SepaDetailsEntity": {
"type": "object",
"properties": {
"bankName": {
"type": "string"
},
"bankAccountNumber": {
"nullable": true,
"description": "Full bank account number (PII). Nullable / omitted by default. Returned only when your organization has been granted access to full payment-instruction details. Contact support to enable.",
"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": {
"nullable": true,
"description": "Beneficiary bank address. The beneficiary's own address is taken from the identity.",
"allOf": [
{
"$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 native ETH).",
"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)\nwhich can be either a BLS public key or an Ethereum account address. This parameter currently accepts ETH1 and BLS withdrawal credentials, but it is\nconsidered deprecated after the Capella/Shanghai fork. All users are now advised to use an ETH1 withdrawal address, specified through the\n`withdrawal_address` parameter as this is required to enable the ongoing accrual of rewards.\nFor more information regarding creating withdrawal credentials, please see the official\n[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"
],
"additionalProperties": false
},
"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"
],
"additionalProperties": false
},
"SessionStatusResponse": {
"type": "string",
"enum": [
"active",
"completed",
"archived"
]
},
"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. The persisted `uint_256` column rejects a\nnegative value, so the documented decimal grammar carries no sign.",
"type": "string",
"format": "decimal",
"pattern": "^[0-9]+(\\.[0-9]+)?$"
}
},
"required": [
"asset_code",
"role"
]
},
"SetConnectorRequest": {
"description": "Registers a connector under a name and points it at a service URL.",
"type": "object",
"properties": {
"name": {
"description": "Name the connector is registered under. Knova uses it to route calls to this connector.",
"type": "string"
},
"url": {
"description": "Base URL of the service that implements the connector contract.",
"type": "string"
}
},
"required": [
"name",
"url"
]
},
"SetIdentityResponse": {
"type": "object",
"properties": {
"id": {
"description": "Id of the user",
"type": "string",
"format": "uuid"
}
},
"required": [
"id"
]
},
"SetPaymentAccountRequest": {
"description": "Request to set a payment account. `data` carries the details the vendor named by `type` requires.",
"type": "object",
"properties": {
"type": {
"example": "vendor_a",
"description": "Vendor integration the payment account belongs to.",
"type": "string"
},
"data": {
"description": "Vendor-specific payment account details, as JSON.",
"type": "object"
}
},
"required": [
"type",
"data"
]
},
"SetPaymentAccountResponse": {
"description": "Response after setting a payment account.",
"type": "object",
"properties": {
"id": {
"description": "ID of the created payment account record",
"type": "string",
"format": "uuid"
}
},
"required": [
"id"
]
},
"SetTempoZoneMembershipRequest": {
"description": "Request body identifying the Tempo Zone a user should be assigned to.",
"type": "object",
"properties": {
"zone_key": {
"description": "Key of the zone to assign the user to, referencing the Tempo integration's zone registry",
"type": "string"
}
},
"required": [
"zone_key"
]
},
"SetVendorIdentityRequest": {
"description": "Body of a request to submit a user's stored identity to a vendor.",
"type": "object",
"properties": {
"documents": {
"description": "Documents to upload to the vendor (vendor-specific)",
"type": "array",
"items": {
"$ref": "#/components/schemas/IdentityDocumentCreateDto"
}
}
}
},
"SetVendorIdentityResponse": {
"type": "object",
"properties": {
"id": {
"description": "Id of the user",
"type": "string",
"format": "uuid"
},
"tos_link": {
"nullable": true,
"description": "Link to the Terms of Service acceptance form (vendor-specific)",
"type": "string"
},
"tos_accepted": {
"nullable": true,
"description": "Indicate if the Terms of Service has been accepted (vendor-specific)",
"type": "boolean"
}
},
"required": [
"id"
]
},
"SetWorkflowTemplateOperatorSelectableParams": {
"description": "Query parameters selecting one workflow template version to update.",
"type": "object",
"properties": {
"version": {
"nullable": true,
"description": "Version to update; every stored version is updated when omitted",
"type": "string",
"format": "semver",
"pattern": "^(0|[1-9][0-9]{0,18})\\.(0|[1-9][0-9]{0,18})\\.(0|[1-9][0-9]{0,18})(?:-((?:0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$"
}
}
},
"SetWorkflowTemplateOperatorSelectableRequest": {
"description": "A request changing whether operators may choose a workflow template.",
"type": "object",
"properties": {
"operator_selectable": {
"description": "Whether operators may choose the template directly",
"type": "boolean"
}
},
"required": [
"operator_selectable"
],
"additionalProperties": false
},
"SetWorkflowTemplateParams": {
"description": "Catalog metadata applied when publishing a workflow template.",
"type": "object",
"properties": {
"operator_selectable": {
"nullable": true,
"description": "Whether operators may choose the template directly; defaults to true",
"type": "boolean"
}
}
},
"Settlement": {
"type": "object",
"properties": {
"to_user_id": {
"nullable": true,
"description": "User id receiving the assets",
"type": "string",
"format": "uuid"
},
"from_user_id": {
"nullable": true,
"description": "User id sending the assets",
"type": "string",
"format": "uuid"
},
"action": {
"description": "Type of action",
"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",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
},
"description": {
"description": "Description of the action",
"type": "string"
},
"created": {
"description": "Timestamp when the transaction was created",
"type": "string",
"format": "date-time"
}
},
"required": [
"action",
"asset_code",
"amount",
"description",
"created"
]
},
"Settlements": {
"type": "object",
"properties": {
"settlements": {
"description": "List of settlements for the transaction",
"type": "array",
"items": {
"$ref": "#/components/schemas/Settlement"
}
}
},
"required": [
"settlements"
]
},
"Sex": {
"type": "string",
"enum": [
"Male",
"Female"
]
},
"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": {
"id": {
"description": "Transaction ID (uetr) for the submitted contract.",
"type": "string",
"format": "uuid"
},
"service_provider_staking_data": {
"$ref": "#/components/schemas/ServiceProviderStakingData"
}
},
"required": [
"id",
"service_provider_staking_data"
]
},
"SubmitWorkflowContractRequest": {
"description": "Request for submitting an assembled workflow contract instance.",
"type": "object",
"properties": {
"external_id": {
"description": "Unique ID to ensure idempotency",
"type": "string"
},
"data": {
"description": "Assembled workflow instance: the inlined template document, role bindings keyed by role\nname, template parameters, and the decimal scale of every asset the workflow touches.\n\nThe template document must remain on the wire (callers and future create/save flows still\nsend it). Execution authority comes from the stored catalog row for\n`template.id` + `template.version`, not from the caller-supplied body text.",
"type": "object"
},
"participants": {
"description": "Exchange user IDs of additional participants that must sign the contract. Users bound to\na template role are derived from the instance data and do not need to be listed here.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"memo": {
"nullable": true,
"description": "Optional memo attached to the contract",
"type": "string"
}
},
"required": [
"external_id",
"data",
"participants"
]
},
"SubmitWorkflowContractResponse": {
"description": "Response identifying the submitted workflow contract.",
"type": "object",
"properties": {
"id": {
"description": "Transaction ID (uetr) for the submitted contract",
"type": "string",
"format": "uuid"
}
},
"required": [
"id"
]
},
"SwapLegRequest": {
"description": "The amount and fee configuration for one leg of a swap.",
"type": "object",
"properties": {
"asset_code": {
"description": "Asset code for this leg (e.g. \"ETH\", \"BTC\")",
"type": "string"
},
"amount": {
"description": "Amount to transfer in this leg",
"type": "string",
"format": "decimal",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
},
"fee_level": {
"$ref": "#/components/schemas/FeeLevel"
},
"vendor": {
"nullable": true,
"description": "Optional custody vendor for this leg; defaults to the platform default",
"allOf": [
{
"$ref": "#/components/schemas/CustodyVendor"
}
]
}
},
"required": [
"asset_code",
"amount",
"fee_level"
]
},
"SwiftDetailsEntity": {
"type": "object",
"properties": {
"accountHolderName": {
"type": "string"
},
"bankAccountNumber": {
"nullable": true,
"description": "Full bank account number (PII). Nullable / omitted by default. Returned only when your organization has been granted access to full payment-instruction details. Contact support to enable.",
"type": "string"
},
"iban": {
"nullable": true,
"description": "Full IBAN (PII). Nullable / omitted by default. Returned only when your organization has been granted access to full payment-instruction details. Contact support to enable.",
"type": "string"
},
"bankAccountNumberLast4": {
"nullable": true,
"type": "string"
},
"swiftOrBicNumber": {
"nullable": true,
"type": "string"
},
"ibanLast4": {
"nullable": true,
"type": "string"
},
"address": {
"nullable": true,
"description": "Beneficiary bank address. Optional; required for SWIFT payouts. The beneficiary's own address is taken from the identity.",
"allOf": [
{
"$ref": "#/components/schemas/PostalAddressEntity"
}
]
},
"bankSlug": {
"nullable": true,
"type": "string"
},
"bankName": {
"nullable": true,
"type": "string"
},
"bankAccountType": {
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/BankAccountType"
}
]
},
"intermediaryBankName": {
"nullable": true,
"type": "string"
},
"intermediaryBankSwiftOrBicNumber": {
"nullable": true,
"type": "string"
},
"intermediaryBankRoutingNumber": {
"nullable": true,
"type": "string"
},
"intermediaryBankAddress": {
"nullable": true,
"type": "string"
},
"beneficiaryBankCnapsCode": {
"nullable": true,
"type": "string"
},
"beneficiaryPhone": {
"nullable": true,
"type": "string"
},
"beneficiaryAddressInChinese": {
"nullable": true,
"type": "string"
},
"recipientRelationship": {
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/RecipientRelationship"
}
]
},
"bankAddress": {
"nullable": true,
"description": "Deprecated. Use the structured `address` field for the beneficiary bank address.",
"type": "string"
}
},
"required": [
"accountHolderName"
]
},
"TemplateResult": {
"type": "object",
"properties": {
"period_end": {
"description": "End of the reporting period in RFC3339 format",
"type": "string",
"format": "date-time"
},
"values": {
"description": "Per-asset values for this period",
"type": "array",
"items": {
"$ref": "#/components/schemas/TemplateResultValue"
}
},
"commitments": {
"description": "Number of commitments included in this entry",
"type": "integer",
"format": "int64",
"minimum": -9223372036854775808,
"maximum": 9223372036854775807
},
"applied": {
"description": "Whether this result has been applied",
"type": "boolean"
}
},
"required": [
"period_end",
"values",
"commitments",
"applied"
]
},
"TemplateResultValue": {
"type": "object",
"properties": {
"asset_code": {
"description": "Asset code (e.g. BTC)",
"type": "string"
},
"amount": {
"description": "Amount of the asset",
"type": "string",
"format": "decimal",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
}
},
"required": [
"asset_code",
"amount"
]
},
"TempoZoneMembership": {
"description": "A user's assignment to a single Tempo Zone, which determines how their Tempo transfers route.",
"type": "object",
"properties": {
"user_id": {
"description": "Id of the user",
"type": "string",
"format": "uuid"
},
"zone_key": {
"description": "Key of the zone the user belongs to, referencing the Tempo integration's zone registry",
"type": "string"
}
},
"required": [
"user_id",
"zone_key"
]
},
"TokenAssetData": {
"description": "On-chain token addresses for an asset, stored in the `token_data` column of `asset_codes`.",
"type": "object",
"properties": {
"token_address": {
"description": "On-chain ERC-20 contract address of the asset.",
"type": "string"
},
"pool_address": {
"nullable": true,
"description": "On-chain address of the Aave pool contract that deposit and borrow calls target, when the\nasset participates in lending.",
"type": "string"
}
},
"required": [
"token_address"
]
},
"TokenQuote": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64",
"minimum": -9223372036854775808,
"maximum": 9223372036854775807
},
"name": {
"type": "string"
},
"symbol": {
"type": "string"
},
"slug": {
"type": "string"
},
"num_market_pairs": {
"nullable": true,
"type": "integer",
"format": "int64",
"minimum": -9223372036854775808,
"maximum": 9223372036854775807
},
"date_added": {
"nullable": true,
"type": "string"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"max_supply": {
"nullable": true,
"type": "number"
},
"circulating_supply": {
"nullable": true,
"type": "number"
},
"total_supply": {
"nullable": true,
"type": "number"
},
"is_active": {
"nullable": true,
"type": "integer",
"format": "int64",
"minimum": -9223372036854775808,
"maximum": 9223372036854775807
},
"infinite_supply": {
"nullable": true,
"type": "boolean"
},
"minted_market_cap": {
"nullable": true,
"type": "number"
},
"platform": {
"nullable": true,
"type": "object"
},
"cmc_rank": {
"nullable": true,
"type": "integer",
"format": "int64",
"minimum": -9223372036854775808,
"maximum": 9223372036854775807
},
"is_fiat": {
"nullable": true,
"type": "integer",
"format": "int64",
"minimum": -9223372036854775808,
"maximum": 9223372036854775807
},
"self_reported_circulating_supply": {
"nullable": true,
"type": "number"
},
"self_reported_market_cap": {
"nullable": true,
"type": "number"
},
"tvl_ratio": {
"nullable": true,
"type": "number"
},
"last_updated": {
"type": "string"
},
"quote": {
"$ref": "#/components/schemas/AssetQuote"
}
},
"required": [
"id",
"name",
"symbol",
"slug",
"tags",
"last_updated",
"quote"
]
},
"TradeType": {
"type": "string",
"enum": [
"Purchase",
"Sale"
]
},
"TransactionResponse": {
"type": "object",
"properties": {
"success": {
"description": "Whether the resend was successful",
"type": "boolean"
}
},
"required": [
"success"
]
},
"TxFailuresResponse": {
"type": "object",
"properties": {
"messages_count": {
"description": "Number of successfully resent messages",
"type": "integer",
"format": "int64",
"minimum": 0,
"maximum": 4294967295
}
},
"required": [
"messages_count"
]
},
"UkfpsDetailsCreateDto": {
"type": "object",
"properties": {
"iban": {
"description": "UK IBAN. Required: UK FPS payouts cannot be created without it, and the sort code and account number are derived from it.",
"type": "string"
},
"localRoutingCode": {
"nullable": true,
"description": "UK sort code (6 digits, hyphens optional). Optional — auto-derived from the IBAN. If provided, must match the IBAN.",
"type": "string"
},
"bankAccountNumber": {
"nullable": true,
"description": "UK bank account number (8 digits). Optional — auto-derived from the IBAN. If provided, must match the IBAN.",
"type": "string"
},
"bankName": {
"nullable": true,
"description": "Bank name, e.g. Barclays.",
"type": "string"
},
"bankSlug": {
"nullable": true,
"description": "Anonymized bank slug returned by the institutions list endpoint.",
"type": "string"
},
"bankAccountType": {
"nullable": true,
"description": "Account type (Checking or Savings).",
"allOf": [
{
"$ref": "#/components/schemas/BankAccountType"
}
]
},
"address": {
"nullable": true,
"description": "Beneficiary bank address. Optional; required only for certain countries/corridors. The beneficiary's own address is taken from the identity.",
"allOf": [
{
"$ref": "#/components/schemas/PostalAddressCreateDto"
}
]
}
},
"required": [
"iban"
]
},
"UkfpsDetailsEntity": {
"type": "object",
"properties": {
"bankName": {
"nullable": true,
"type": "string"
},
"bankSlug": {
"nullable": true,
"type": "string"
},
"bankAccountNumber": {
"nullable": true,
"description": "Full bank account number (PII). Nullable / omitted by default. Returned only when your organization has been granted access to full payment-instruction details. Contact support to enable.",
"type": "string"
},
"bankAccountNumberLast4": {
"nullable": true,
"type": "string"
},
"sortCode": {
"nullable": true,
"description": "6-digit UK sort code (derived from IBAN positions 9-14).",
"type": "string"
},
"iban": {
"nullable": true,
"description": "Full IBAN (PII). Nullable / omitted by default. Returned only when your organization has been granted access to full payment-instruction details. Contact support to enable.",
"type": "string"
},
"ibanLast4": {
"nullable": true,
"type": "string"
},
"accountHolderName": {
"nullable": true,
"type": "string"
},
"bankAccountType": {
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/BankAccountType"
}
]
},
"address": {
"nullable": true,
"description": "Beneficiary bank address. The beneficiary's own address is taken from the identity.",
"allOf": [
{
"$ref": "#/components/schemas/PostalAddressEntity"
}
]
}
}
},
"UnstakeRequest": {
"description": "Carries the information required to initiate a validator exit and issue unstaked funds.",
"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"
]
},
"UnstakeResponse": {
"description": "Returns the identifier of the submitted unstake contract transaction.",
"type": "object",
"properties": {
"id": {
"description": "Transaction ID (uetr) for the submitted unstake contract.",
"type": "string",
"format": "uuid"
}
},
"required": [
"id"
]
},
"UpdateAuthUserRequest": {
"type": "object",
"properties": {
"first_name": {
"nullable": true,
"description": "User first name",
"type": "string"
},
"last_name": {
"nullable": true,
"description": "User last name",
"type": "string"
},
"username": {
"nullable": true,
"description": "Unique username for the user",
"type": "string"
},
"email": {
"nullable": true,
"description": "User email address",
"type": "string"
}
}
},
"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",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
},
"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",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
},
"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",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
},
"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": {
"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"
}
}
},
"UpsertPolicyRuleRequest": {
"description": "Request to create or update a policy rule.",
"type": "object",
"properties": {
"id": {
"description": "Unique policy rule id.",
"type": "string",
"format": "uuid"
},
"name": {
"description": "Human-readable rule name.",
"type": "string"
},
"description": {
"nullable": true,
"description": "Optional rule description.",
"type": "string"
},
"priority": {
"description": "Rule priority; higher-priority rules are evaluated first.",
"type": "integer",
"format": "int32",
"minimum": -2147483648,
"maximum": 2147483647
},
"condition_json": {
"description": "JSON condition matched against tool evaluation context.",
"type": "object"
},
"outcome_json": {
"description": "JSON policy outcome applied when the condition matches.",
"type": "object"
},
"reason": {
"description": "Human-readable reason recorded with matching decisions.",
"type": "string"
},
"managed": {
"description": "Whether the rule is system-managed.",
"type": "boolean"
}
},
"required": [
"id",
"name",
"priority",
"condition_json",
"outcome_json",
"reason",
"managed"
]
},
"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"
},
"recipientRelationship": {
"nullable": true,
"description": "The relationship between the sender and the recipient. Required by some payment providers.",
"allOf": [
{
"$ref": "#/components/schemas/RecipientRelationship"
}
]
},
"address": {
"nullable": true,
"description": "Beneficiary bank address. Optional; required only for certain countries/corridors. The beneficiary's own address is taken from the identity.",
"allOf": [
{
"$ref": "#/components/schemas/PostalAddressCreateDto"
}
]
}
},
"required": [
"accountHolderName",
"bankAccountNumber",
"bankRoutingNumber",
"bankAccountType"
]
},
"UsDetailsEntity": {
"type": "object",
"properties": {
"bankName": {
"nullable": true,
"type": "string"
},
"accountHolderName": {
"type": "string"
},
"bankAccountNumber": {
"nullable": true,
"description": "Full bank account number (PII). Nullable / omitted by default. Returned only when your organization has been granted access to full payment-instruction details. Contact support to enable.",
"type": "string"
},
"bankAccountNumberLast4": {
"type": "string"
},
"bankRoutingNumber": {
"type": "string"
},
"bankAccountType": {
"$ref": "#/components/schemas/BankAccountType"
},
"recipientRelationship": {
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/RecipientRelationship"
}
]
},
"address": {
"nullable": true,
"description": "Beneficiary bank address. The beneficiary's own address is taken from the identity.",
"allOf": [
{
"$ref": "#/components/schemas/PostalAddressEntity"
}
]
},
"bankSlug": {
"nullable": true,
"type": "string"
},
"bankCode": {
"nullable": true,
"type": "string"
},
"phone": {
"nullable": true,
"type": "string"
},
"taxId": {
"nullable": true,
"type": "string"
}
},
"required": [
"accountHolderName",
"bankAccountNumberLast4",
"bankRoutingNumber",
"bankAccountType"
]
},
"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",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
},
"external_custody_amount": {
"description": "Amount of asset held in external custody",
"type": "string",
"format": "decimal",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
}
},
"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",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
}
},
"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"
]
},
"UserBalanceListParams": {
"type": "object",
"properties": {
"asset_code": {
"nullable": true,
"description": "Optional asset code filter, matching any one of the codes named. Omit to include all assets.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"user_id": {
"nullable": true,
"description": "Optional filter on the identifier of the user holding the balance, matching any one of the\nidentifiers named.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"minItems": 1,
"maxItems": 200
},
"verifier": {
"nullable": true,
"description": "Optional exact filter on the wallet verifier of the user holding the balance, matching any\none of the verifiers named.",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200
},
"username": {
"nullable": true,
"description": "Optional case-insensitive search for text anywhere in the username of the user holding the\nbalance. A term of one or two characters must equal the whole username instead.",
"type": "string",
"pattern": "\\S",
"minLength": 1
},
"disabled_assets": {
"description": "Whether to return disabled assets instead of enabled ones, excluding them when omitted.",
"type": "boolean"
},
"page": {
"description": "Page number for paginated results, defaulting to the first page.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"page_size": {
"description": "Page size for paginated results, defaulting to 50 and capped at 200.",
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"sort_by": {
"$ref": "#/components/schemas/UserBalanceSortKey"
},
"sort_dir": {
"description": "Direction the results are ordered in, defaulting to ascending.",
"type": "string",
"enum": [
"asc",
"desc"
]
}
}
},
"UserBalanceSortKey": {
"type": "string",
"enum": [
"username",
"asset_code",
"amount"
]
},
"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"
]
},
"UserSort": {
"type": "string",
"enum": [
"username",
"user_type",
"created"
]
},
"UserTypeFilter": {
"type": "string",
"enum": [
"Customer",
"Treasury",
"Authority"
]
},
"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": {
"example": "vendor_a",
"description": "Identifier of a configured vendor integration.",
"type": "string"
},
"VendorAssetBalanceParams": {
"description": "Vendor selection for the complete per-asset lookup.",
"type": "object",
"properties": {
"vendors": {
"description": "Optional list of vendors to filter by. Comma-separated vendor identifiers.",
"type": "string",
"format": "comma-separated-array"
}
}
},
"VendorBalanceSortKey": {
"type": "string",
"enum": [
"vendor",
"asset_code",
"asset_vendor_code",
"balance"
]
},
"VendorCodeInfo": {
"type": "object",
"properties": {
"code": {
"description": "The vendor-specific code for the asset (e.g. ETH_TEST5).",
"type": "string"
},
"omnibus_vault_id": {
"description": "The omnibus vault ID for this vendor and asset.",
"type": "string"
}
},
"required": [
"code",
"omnibus_vault_id"
]
},
"VendorTarget": {
"example": "vendor_a",
"description": "Identifier of the vendor integration to act on.",
"type": "string"
},
"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",
"format": "int64",
"minimum": 0,
"maximum": 4294967295
}
},
"required": [
"notification",
"delivery_status",
"target_url",
"attempted",
"attempt_count"
]
},
"WebhookDeliverySort": {
"type": "string",
"enum": [
"created",
"attempted",
"delivery_status",
"target_url"
]
},
"WebhookDeliveryStatus": {
"type": "string",
"enum": [
"Pending",
"Delivered",
"Failed"
]
},
"WebhookNotification": {
"type": "object",
"properties": {
"id": {
"description": "ID for this webhook event",
"type": "string"
},
"uetr": {
"nullable": true,
"description": "Unique End-to-end Transaction Reference",
"type": "string"
},
"event_type": {
"$ref": "#/components/schemas/EventType"
},
"created": {
"description": "Timestamp of when the event was created",
"type": "string",
"format": "date-time"
},
"payload": {
"description": "Data associated with the event, contents of WebhookPayload* (i.e. WebhookPayloadInitial, etc.)",
"type": "object"
}
},
"required": [
"id",
"event_type",
"created",
"payload"
]
},
"WebhookPayloadApprovalRequest": {
"type": "object",
"properties": {
"to_user_id": {
"description": "User id receiving the assets",
"type": "string"
},
"from_user_id": {
"description": "User id sending the assets",
"type": "string"
},
"contract_type": {
"$ref": "#/components/schemas/ContractType"
},
"asset_code": {
"description": "Asset code (e.g. BTC)",
"type": "string"
},
"amount": {
"description": "Amount of the asset sent or received",
"type": "string",
"format": "decimal",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
},
"created": {
"description": "Timestamp when the approval request was created",
"type": "string",
"format": "date-time"
},
"updated": {
"description": "Timestamp when the approval request was updated",
"type": "string",
"format": "date-time"
}
},
"required": [
"to_user_id",
"from_user_id",
"contract_type",
"asset_code",
"amount",
"created",
"updated"
]
},
"WebhookPayloadDigitalTwinTransaction": {
"type": "object",
"properties": {
"to_user_id": {
"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_user_id": {
"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",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
},
"action_type": {
"$ref": "#/components/schemas/DigitalTwinTransactionType"
},
"description": {
"nullable": true,
"description": "Description of the action",
"type": "string"
},
"created": {
"description": "Timestamp when the transaction was created",
"type": "string",
"format": "date-time"
}
},
"required": [
"asset_code",
"amount",
"action_type",
"created"
]
},
"WebhookPayloadFiat": {
"type": "object",
"properties": {
"to_user_id": {
"nullable": true,
"description": "User id receiving the assets",
"type": "string",
"format": "uuid"
},
"from_user_id": {
"nullable": true,
"description": "User id sending the assets",
"type": "string",
"format": "uuid"
},
"asset_code": {
"description": "Asset code (e.g. USD)",
"type": "string"
},
"net": {
"description": "Amount of the asset sent or received",
"type": "string",
"format": "decimal",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
},
"fee": {
"nullable": true,
"description": "Fee paid if any",
"type": "string",
"format": "decimal",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
},
"status": {
"description": "Status of the transaction",
"type": "string"
},
"created": {
"description": "Timestamp when the transaction was created",
"type": "string",
"format": "date-time"
}
},
"required": [
"asset_code",
"net",
"status",
"created"
]
},
"WebhookPayloadFinal": {
"type": "object",
"properties": {
"status": {
"$ref": "#/components/schemas/ContractStatus"
},
"status_info": {
"nullable": true,
"description": "Info about the final status of the transaction",
"type": "string"
},
"created": {
"description": "Timestamp when the contract was closed",
"type": "string",
"format": "date-time"
}
},
"required": [
"status",
"created"
]
},
"WebhookPayloadInitial": {
"type": "object",
"properties": {
"status": {
"$ref": "#/components/schemas/ContractStatus"
},
"contract_type": {
"$ref": "#/components/schemas/ContractType"
},
"idempotency_key": {
"nullable": true,
"description": "Idempotency key passed in when creating the transaction",
"type": "string"
},
"from_user_id": {
"nullable": true,
"description": "User ID of the sender",
"type": "string",
"format": "uuid"
},
"from_username": {
"nullable": true,
"description": "Username of the sender",
"type": "string"
},
"to_user_id": {
"nullable": true,
"description": "User ID of the recipient",
"type": "string",
"format": "uuid"
},
"to_username": {
"nullable": true,
"description": "Username of the recipient",
"type": "string"
},
"request": {
"description": "Request data provided through the endpoint that initiated this transaction",
"type": "object"
},
"memo": {
"nullable": true,
"description": "Memo passed in when creating the transaction",
"type": "string"
}
},
"required": [
"status",
"contract_type",
"request"
]
},
"WebhookPayloadOnchain": {
"type": "object",
"properties": {
"to_address": {
"nullable": true,
"description": "Address receiving the assets",
"allOf": [
{
"$ref": "#/components/schemas/Address"
}
]
},
"from_address": {
"nullable": true,
"description": "Address sending the assets",
"allOf": [
{
"$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",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
},
"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",
"pattern": "^-?[0-9]+(\\.[0-9]+)?$"
},
"fee_level": {
"nullable": true,
"description": "Fee level used for the transaction",
"allOf": [
{
"$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 onchain transaction was created",
"type": "string",
"format": "date-time"
},
"updated": {
"description": "Timestamp when the onchain transaction was updated",
"type": "string",
"format": "date-time"
}
},
"required": [
"asset_code",
"amount",
"fee_asset_code",
"network_fee",
"status",
"created",
"updated"
]
},
"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"
]
},
"WebhookSubscriptionSort": {
"type": "string",
"enum": [
"created",
"url",
"active"
]
},
"WorkflowTemplate": {
"description": "A stored workflow contract template together with its full JSON definition.",
"type": "object",
"properties": {
"workflow_id": {
"description": "Identifier of the workflow template, taken from the template's `id` field",
"type": "string"
},
"version": {
"description": "Semantic version of the workflow template, taken from the template's `version` field",
"type": "string"
},
"description": {
"description": "Human-readable description of what the workflow template does",
"type": "string"
},
"operator_selectable": {
"description": "Whether an operator may choose this template directly",
"type": "boolean"
},
"data": {
"description": "The full workflow template document, ready to be submitted as contract workflow data",
"type": "object"
},
"created": {
"description": "Timestamp at which this template version was first stored",
"type": "string",
"format": "date-time"
},
"updated": {
"description": "Timestamp at which this template version was last stored",
"type": "string",
"format": "date-time"
}
},
"required": [
"workflow_id",
"version",
"description",
"operator_selectable",
"data",
"created",
"updated"
]
},
"WorkflowTemplateSummary": {
"description": "A stored workflow contract template without its definition, used to choose between templates.",
"type": "object",
"properties": {
"workflow_id": {
"description": "Identifier of the workflow template, taken from the template's `id` field",
"type": "string"
},
"version": {
"description": "Semantic version of the workflow template, taken from the template's `version` field",
"type": "string"
},
"description": {
"description": "Human-readable description of what the workflow template does",
"type": "string"
},
"operator_selectable": {
"description": "Whether an operator may choose this template directly. Example and demonstration templates\nset this false so they are not offered as real work; templates published before the field\nexisted report true.",
"type": "boolean"
},
"updated": {
"description": "Timestamp at which this template version was last stored",
"type": "string",
"format": "date-time"
}
},
"required": [
"workflow_id",
"version",
"description",
"operator_selectable",
"updated"
]
}
}
}
}