{ "openapi": "3.1.0", "info": { "title": "Ospree Directory API", "description": "Counterparty directory: customer accounts (entities and individuals) and the VASP directory.", "version": "2.0.0" }, "paths": { "/api/v2/directory/accounts": { "post": { "tags": [ "Accounts" ], "summary": "Create Account", "description": "This endpoint is used to create a new account within the directory module. It can create 'individual' or 'entity' accounts.", "operationId": "Create_Account_api_v2_directory_accounts_post", "security": [ { "HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDetails" }, "examples": { "individual": { "summary": "An individual customer", "description": "An individual needs at least one of: a customer ID, complete birth information (place AND date together), an address, or a national ID.", "value": { "reference_id": "johndoe", "account_type": "individual", "account_category": "customer", "email": "john.doe@example.com", "customer_id": "CUST-10042", "individual": { "individual_name": { "name_type": "LEGL", "name_first": "John", "name_last": "Doe" }, "date_of_birth": "1990-01-01", "place_of_birth": "Singapore, Singapore", "nationality_country": "SG", "residence_country": "US" }, "address": { "address_type": "GEOG", "address_street_no": "456", "address_street_name": "Elm Street", "address_city": "New York", "address_region": "New York", "address_postcode": "08012", "address_country_code": "US" }, "national_id": { "national_id_type": "CCPT", "national_id": "ABC123456", "issue_country": "US" } } }, "entity": { "summary": "An entity (business) customer", "description": "An entity needs at least one of: a customer ID, an address, or a national ID. For an LEIX national_id the value must be a valid 20-character LEI, and `issue_country` and `registration_authority` must be omitted.", "value": { "reference_id": "digital-capital", "account_type": "entity", "account_category": "non-customer", "email": "ops@digitalcapital.example", "entity": { "entity_name": { "name_type": "LEGL", "name_legal": "Digital Capital", "name_business": "Digital Capital Pte. Ltd." }, "registration_country": "SG" }, "address": { "address_type": "GEOG", "address_line": "1 Raffles Place", "address_city": "Singapore", "address_country_code": "SG" }, "national_id": { "national_id_type": "LEIX", "national_id": "5493001KJTIIGC8Y1R12" } } } } } } }, "responses": { "200": { "description": "The account was created. The body echoes it in the same nested shape.", "content": { "application/json": { "schema": {}, "example": { "status": "success", "data": { "reference_id": "johndoe", "account_type": "individual", "account_category": "customer", "email": "john.doe@example.com", "customer_id": "CUST-10042", "individual": { "individual_name": { "name_type": "LEGL", "name_first": "John", "name_last": "Doe" }, "date_of_birth": "1990-01-01", "place_of_birth": "Singapore, Singapore", "nationality_country": "SG", "residence_country": "US" }, "address": { "address_type": "GEOG", "address_street_no": "456", "address_street_name": "Elm Street", "address_city": "New York", "address_region": "New York", "address_postcode": "08012", "address_country_code": "US" }, "national_id": { "national_id_type": "CCPT", "national_id": "ABC123456", "issue_country": "US" }, "created": "2026-08-31T09:14:22.418293" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "status": "fail", "message": "Authentication required.", "error_code": "auth.unauthenticated" }, "schema": { "$ref": "#/components/schemas/ApiFailResponse" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "example": { "status": "fail", "message": "Payment required.", "error_code": "billing.payment_required" }, "schema": { "$ref": "#/components/schemas/ApiFailResponse" } } } }, "422": { "description": "Unprocessable Entity - Validation Error", "content": { "application/json": { "example": { "status": "fail", "message": "Validation error", "data": [ { "loc": [ "body", "reference_id" ], "msg": "Field required", "type": "missing" } ] }, "schema": { "$ref": "#/components/schemas/ApiFailResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "example": { "status": "error", "code": 500, "message": "Something went wrong.", "error_code": "internal_error" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } }, "get": { "tags": [ "Accounts" ], "summary": "List Accounts", "description": "This endpoint retrieves a list of all accounts within the directory.", "operationId": "List_Accounts_api_v2_directory_accounts_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 30, "title": "Size" } }, { "name": "sort", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sort" } }, { "name": "start_range", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Start Range" } }, { "name": "end_range", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "End Range" } }, { "name": "account_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Account Type" } }, { "name": "account_category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Account Category" } } ], "responses": { "200": { "description": "A page of accounts. Page size is 50; the default sort is by creation date.", "content": { "application/json": { "schema": {}, "examples": { "one_page": { "summary": "A page of accounts", "description": "A flat projection: `name` is one joined string, not the nested name object the create and retrieve bodies use.", "value": { "status": "success", "data": { "items": [ { "reference_id": "johndoe", "account_type": "individual", "name": "John Doe", "account_category": "customer", "email": "john.doe@example.com", "created": "2026-08-31T09:14:22.418293", "last_modified": "2026-08-31T10:02:11.104882" }, { "reference_id": "digital-capital", "account_type": "entity", "name": "Digital Capital Pte. Ltd.", "account_category": "non-customer", "email": "ops@digitalcapital.example", "created": "2026-08-30T14:41:09.220417" } ], "pagination": { "total": 2, "size": 50, "page": 1 } } } }, "empty_page": { "summary": "No accounts", "value": { "status": "success", "data": { "items": [], "pagination": { "total": 0, "size": 50, "page": 1 } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "status": "fail", "message": "Authentication required.", "error_code": "auth.unauthenticated" }, "schema": { "$ref": "#/components/schemas/ApiFailResponse" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "example": { "status": "fail", "message": "Payment required.", "error_code": "billing.payment_required" }, "schema": { "$ref": "#/components/schemas/ApiFailResponse" } } } }, "422": { "description": "Unprocessable Entity - Validation Error", "content": { "application/json": { "example": { "status": "fail", "message": "Validation error", "data": [ { "loc": [ "query", "account_type" ], "msg": "Field required", "type": "missing" } ] }, "schema": { "$ref": "#/components/schemas/ApiFailResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "example": { "status": "error", "code": 500, "message": "Something went wrong.", "error_code": "internal_error" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v2/directory/accounts/search": { "get": { "tags": [ "Accounts" ], "summary": "Search Account", "description": "This endpoint allows users to search for accounts based on a search term and optional filters such as account category and account type.", "operationId": "Search_Account_api_v2_directory_accounts_search_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "search_term", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search Term" } }, { "name": "account_category", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/CustomerFilterType" }, { "type": "null" } ], "title": "Account Category" } }, { "name": "account_type", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/AccountTypeString" }, { "type": "null" } ], "title": "Account Type" } } ], "responses": { "200": { "description": "Matching accounts as a BARE ARRAY -- this operation does not use the `{status, data}` envelope the rest of this plane returns.", "content": { "application/json": { "schema": {}, "examples": { "matches": { "summary": "Two matches (note: no envelope)", "value": [ { "reference_id": "johndoe", "account_type": "individual", "name": "John Doe", "account_category": "customer", "email": "john.doe@example.com", "created": "2026-08-31T09:14:22.418293", "last_modified": "2026-08-31T10:02:11.104882" }, { "reference_id": "johndoe-2", "account_type": "individual", "name": "John Doe", "account_category": "non-customer", "email": "j.doe@example.org", "created": "2026-08-29T08:11:50.771233" } ] }, "no_matches": { "summary": "No matches -- an empty array, not a 404", "value": [] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "status": "fail", "message": "Authentication required.", "error_code": "auth.unauthenticated" }, "schema": { "$ref": "#/components/schemas/ApiFailResponse" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "example": { "status": "fail", "message": "Payment required.", "error_code": "billing.payment_required" }, "schema": { "$ref": "#/components/schemas/ApiFailResponse" } } } }, "422": { "description": "Unprocessable Entity - Validation Error", "content": { "application/json": { "example": { "status": "fail", "message": "Validation error", "data": [ { "loc": [ "query", "search_term" ], "msg": "Field required", "type": "missing" } ] }, "schema": { "$ref": "#/components/schemas/ApiFailResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "example": { "status": "error", "code": 500, "message": "Something went wrong.", "error_code": "internal_error" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v2/directory/accounts/{reference_id}": { "get": { "tags": [ "Accounts" ], "summary": "Retrieve Account", "description": "This endpoint retrieves the details of a specific account identified by {reference_id}.", "operationId": "Retrieve_Account_api_v2_directory_accounts__reference_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "reference_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Unique identifier for the account, previously external_id.", "title": "Reference Id" }, "description": "Unique identifier for the account, previously external_id." } ], "responses": { "200": { "description": "The account, in the same nested shape the create call takes.", "content": { "application/json": { "schema": {}, "examples": { "individual": { "summary": "An individual account", "value": { "status": "success", "data": { "reference_id": "johndoe", "account_type": "individual", "account_category": "customer", "email": "john.doe@example.com", "customer_id": "CUST-10042", "individual": { "individual_name": { "name_type": "LEGL", "name_first": "John", "name_last": "Doe" }, "date_of_birth": "1990-01-01", "place_of_birth": "Singapore, Singapore", "nationality_country": "SG", "residence_country": "US" }, "address": { "address_type": "GEOG", "address_street_no": "456", "address_street_name": "Elm Street", "address_city": "New York", "address_region": "New York", "address_postcode": "08012", "address_country_code": "US" }, "national_id": { "national_id_type": "CCPT", "national_id": "ABC123456", "issue_country": "US" }, "created": "2026-08-31T09:14:22.418293", "last_modified": "2026-08-31T10:02:11.104882" } } }, "entity": { "summary": "An entity account", "value": { "status": "success", "data": { "reference_id": "digital-capital", "account_type": "entity", "account_category": "non-customer", "email": "ops@digitalcapital.example", "entity": { "entity_name": { "name_type": "LEGL", "name_legal": "Digital Capital", "name_business": "Digital Capital Pte. Ltd." }, "registration_country": "SG" }, "address": { "address_type": "GEOG", "address_line": "1 Raffles Place", "address_city": "Singapore", "address_country_code": "SG" }, "national_id": { "national_id_type": "LEIX", "national_id": "5493001KJTIIGC8Y1R12" }, "created": "2026-08-30T14:41:09.220417" } } } } } } }, "400": { "description": "No account with this reference_id", "content": { "application/json": { "example": { "status": "fail", "message": "Account does not exist" }, "schema": { "$ref": "#/components/schemas/ApiFailResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "status": "fail", "message": "Authentication required.", "error_code": "auth.unauthenticated" }, "schema": { "$ref": "#/components/schemas/ApiFailResponse" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "example": { "status": "fail", "message": "Payment required.", "error_code": "billing.payment_required" }, "schema": { "$ref": "#/components/schemas/ApiFailResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "example": { "status": "error", "code": 500, "message": "Something went wrong.", "error_code": "internal_error" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } }, "patch": { "tags": [ "Accounts" ], "summary": "Update Account", "description": "This endpoint is utilized to modify/update the details of a specific account identified by {reference_id}. All body inputs are optional. Only provided inputs will be updated in the account record, while all others will maintain their current values.", "operationId": "Update_Account_api_v2_directory_accounts__reference_id__patch", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "reference_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Unique identifier for the account, previously external_id.", "title": "Reference Id" }, "description": "Unique identifier for the account, previously external_id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAccountRequest" }, "examples": { "rename_individual": { "summary": "Change an individual's name and email", "description": "`field` is the path into the nested account shape. Only the listed fields change; everything else keeps its current value.", "value": { "fields": [ { "field": [ "individual", "individual_name", "name_first" ], "value": "Jonathan" }, { "field": [ "individual", "individual_name", "name_last" ], "value": "Doe" }, { "field": [ "email" ], "value": "jonathan.doe@example.com" } ] } }, "update_address": { "summary": "Change one address field", "value": { "fields": [ { "field": [ "address", "address_city" ], "value": "Boston" } ] } } } } } }, "responses": { "200": { "description": "The updated account, re-read after the write.", "content": { "application/json": { "schema": {}, "example": { "status": "success", "data": { "reference_id": "johndoe", "account_type": "individual", "account_category": "customer", "email": "jonathan.doe@example.com", "customer_id": "CUST-10042", "individual": { "individual_name": { "name_type": "LEGL", "name_first": "John", "name_last": "Doe" }, "date_of_birth": "1990-01-01", "place_of_birth": "Singapore, Singapore", "nationality_country": "SG", "residence_country": "US" }, "address": { "address_type": "GEOG", "address_street_no": "456", "address_street_name": "Elm Street", "address_city": "New York", "address_region": "New York", "address_postcode": "08012", "address_country_code": "US" }, "national_id": { "national_id_type": "CCPT", "national_id": "ABC123456", "issue_country": "US" }, "created": "2026-08-31T09:14:22.418293", "last_modified": "2026-08-31T12:30:44.918003" } } } } }, "400": { "description": "No account with this reference_id", "content": { "application/json": { "example": { "status": "fail", "message": "Account does not exist" }, "schema": { "$ref": "#/components/schemas/ApiFailResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "status": "fail", "message": "Authentication required.", "error_code": "auth.unauthenticated" }, "schema": { "$ref": "#/components/schemas/ApiFailResponse" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "example": { "status": "fail", "message": "Payment required.", "error_code": "billing.payment_required" }, "schema": { "$ref": "#/components/schemas/ApiFailResponse" } } } }, "422": { "description": "Unprocessable Entity - Validation Error", "content": { "application/json": { "example": { "status": "fail", "message": "Validation error", "data": [ { "loc": [ "body", "fields", 0, "value" ], "msg": "Field required", "type": "missing" } ] }, "schema": { "$ref": "#/components/schemas/ApiFailResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "example": { "status": "error", "code": 500, "message": "Something went wrong.", "error_code": "internal_error" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } }, "delete": { "tags": [ "Accounts" ], "summary": "Remove Account", "description": "This endpoint is used to remove/delete a specific account identified by {reference_id} from the directory.", "operationId": "Remove_Account_api_v2_directory_accounts__reference_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "reference_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Unique identifier for the account, previously external_id.", "title": "Reference Id" }, "description": "Unique identifier for the account, previously external_id." } ], "responses": { "200": { "description": "The account was deleted. This is a hard delete, not a soft one.", "content": { "application/json": { "schema": {}, "example": { "status": "success", "data": { "message": "Successfully deleted account with reference id of: johndoe" } } } } }, "400": { "description": "No account with this reference_id", "content": { "application/json": { "example": { "status": "fail", "message": "Account does not exist" }, "schema": { "$ref": "#/components/schemas/ApiFailResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "status": "fail", "message": "Authentication required.", "error_code": "auth.unauthenticated" }, "schema": { "$ref": "#/components/schemas/ApiFailResponse" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "example": { "status": "fail", "message": "Payment required.", "error_code": "billing.payment_required" }, "schema": { "$ref": "#/components/schemas/ApiFailResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "example": { "status": "error", "code": 500, "message": "Something went wrong.", "error_code": "internal_error" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v2/directory/vasps": { "get": { "tags": [ "VASPs" ], "summary": "List VASPs", "description": "Retrieve a paginated and sortable list of VASP (Virtual Asset Service Provider) records from the directory.", "operationId": "list_vasps_api_v2_directory_vasps_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 30, "title": "Size" } }, { "name": "sort", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sort" } }, { "name": "start_range", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Start Range" } }, { "name": "end_range", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "End Range" } } ], "responses": { "200": { "description": "A page of VASP records from the directory.", "content": { "application/json": { "schema": {}, "example": { "status": "success", "data": { "items": [ { "vasp_id": "MLESJF", "name_legal": "Meridian Exchange Ltd", "name_business": "Meridian", "address_country_code": "SG", "address_street_no": "1", "address_street_name": "Raffles Place", "address_city": "Singapore", "address_region": "Central", "address_postcode": "048616", "website": "https://meridian.example", "summary": "Regulated virtual asset exchange", "supported_protocols": [ "trisa", "trp" ], "national_id_type_code": "LEIX", "national_id": "5493001KJTIIGC8Y1R12" } ], "pagination": { "total": 1, "size": 50, "page": 1 } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "status": "fail", "message": "Authentication required.", "error_code": "auth.unauthenticated" }, "schema": { "$ref": "#/components/schemas/ApiFailResponse" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "example": { "status": "fail", "message": "Payment required.", "error_code": "billing.payment_required" }, "schema": { "$ref": "#/components/schemas/ApiFailResponse" } } } }, "422": { "description": "Unprocessable Entity - Validation Error", "content": { "application/json": { "example": { "status": "fail", "message": "Validation error", "data": [ { "loc": [ "query", "page" ], "msg": "Field required", "type": "missing" } ] }, "schema": { "$ref": "#/components/schemas/ApiFailResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "example": { "status": "error", "code": 500, "message": "Something went wrong.", "error_code": "internal_error" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v2/directory/vasps/search": { "get": { "tags": [ "VASPs" ], "summary": "Search VASP", "description": "Search for VASP (Virtual Asset Service Provider) records using identifiers such as business or legal names. Returns an empty result set when no matching records are found.\n\nTo find the VASP behind a destination wallet, send `wallet_address` with the `dti` of the asset instead of `search_term`. The result lists the VASPs you can send to that claim the wallet, in the same shape as a name search, including `supported_protocols`; it is empty when no such VASP is known.", "operationId": "search_vasps_api_v2_directory_vasps_search_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "search_term", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search Term" } }, { "name": "wallet_address", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "description": "Find the VASPs you can send to that claim this wallet address. Requires `dti`; not combinable with `search_term`. Returns an empty list when no VASP claims the wallet.", "title": "Wallet Address" }, "description": "Find the VASPs you can send to that claim this wallet address. Requires `dti`; not combinable with `search_term`. Returns an empty list when no VASP claims the wallet." }, { "name": "dti", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "description": "The Digital Token Identifier (ISO 24165) of the asset the wallet holds, e.g. `X9J9K872S` for Ether. Required with `wallet_address`; an unknown DTI is rejected with 422.", "title": "Dti" }, "description": "The Digital Token Identifier (ISO 24165) of the asset the wallet holds, e.g. `X9J9K872S` for Ether. Required with `wallet_address`; an unknown DTI is rejected with 422." } ], "responses": { "200": { "description": "Matching VASPs. Unlike the account search, this one DOES use the `{status, data}` envelope.", "content": { "application/json": { "schema": {}, "examples": { "matches": { "summary": "One match", "value": { "status": "success", "data": [ { "vasp_id": "MLESJF", "name_legal": "Meridian Exchange Ltd", "name_business": "Meridian", "address_country_code": "SG", "address_street_no": "1", "address_street_name": "Raffles Place", "address_city": "Singapore", "address_region": "Central", "address_postcode": "048616", "website": "https://meridian.example", "summary": "Regulated virtual asset exchange", "supported_protocols": [ "trisa", "trp" ], "national_id_type_code": "LEIX", "national_id": "5493001KJTIIGC8Y1R12" } ] } }, "no_matches": { "summary": "No matches -- an empty list, not a 404", "value": { "status": "success", "data": [] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "status": "fail", "message": "Authentication required.", "error_code": "auth.unauthenticated" }, "schema": { "$ref": "#/components/schemas/ApiFailResponse" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "example": { "status": "fail", "message": "Payment required.", "error_code": "billing.payment_required" }, "schema": { "$ref": "#/components/schemas/ApiFailResponse" } } } }, "422": { "description": "Unprocessable Entity - Validation Error", "content": { "application/json": { "example": { "status": "fail", "message": "Validation error", "data": [ { "loc": [ "query", "search_term" ], "msg": "Field required", "type": "missing" } ] }, "schema": { "$ref": "#/components/schemas/ApiFailResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "example": { "status": "error", "code": 500, "message": "Something went wrong.", "error_code": "internal_error" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/v2/directory/vasps/{vasp_id}": { "get": { "tags": [ "VASPs" ], "summary": "Retrieve VASP", "description": "Retrieve a specific VASP (Virtual Asset Service Provider) record from the directory using its unique identifier.", "operationId": "retrieve_vasp_api_v2_directory_vasps__vasp_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "vasp_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the VASP (Virtual Asset Service Provider).", "title": "Vasp Id" }, "description": "The unique identifier of the VASP (Virtual Asset Service Provider)." } ], "responses": { "200": { "description": "The VASP record.", "content": { "application/json": { "schema": {}, "example": { "status": "success", "data": { "vasp_id": "MLESJF", "name_legal": "Meridian Exchange Ltd", "name_business": "Meridian", "address_country_code": "SG", "address_street_no": "1", "address_street_name": "Raffles Place", "address_city": "Singapore", "address_region": "Central", "address_postcode": "048616", "website": "https://meridian.example", "summary": "Regulated virtual asset exchange", "supported_protocols": [ "trisa", "trp" ], "national_id_type_code": "LEIX", "national_id": "5493001KJTIIGC8Y1R12" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "status": "fail", "message": "Authentication required.", "error_code": "auth.unauthenticated" }, "schema": { "$ref": "#/components/schemas/ApiFailResponse" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "example": { "status": "fail", "message": "Payment required.", "error_code": "billing.payment_required" }, "schema": { "$ref": "#/components/schemas/ApiFailResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "example": { "status": "fail", "message": "VASP does not exist" }, "schema": { "$ref": "#/components/schemas/ApiFailResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "example": { "status": "error", "code": 500, "message": "Something went wrong.", "error_code": "internal_error" }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } } }, "components": { "schemas": { "AccountDetails": { "properties": { "reference_id": { "type": "string", "maxLength": 50, "minLength": 4, "title": "Reference Id", "description": "Unique identifier for the account.", "examples": [ "johndoe" ] }, "account_type": { "type": "string", "title": "Account Type", "description": "Type of account, either 'individual' or 'entity'.", "examples": [ "individual", "entity" ] }, "account_category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Account Category", "default": "customer" }, "email": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "null" } ], "title": "Email", "description": "Email address associated with the account." }, "customer_id": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ], "title": "Customer Id", "description": "Customer ID associated with the account." }, "individual": { "anyOf": [ { "$ref": "#/components/schemas/AccountIndividual" }, { "type": "null" } ], "description": "The object that contains the fields specific for an individual account" }, "entity": { "anyOf": [ { "$ref": "#/components/schemas/AccountEntity" }, { "type": "null" } ], "description": "The object that contains the fields specific for an entity account" }, "address": { "anyOf": [ { "$ref": "#/components/schemas/Address" }, { "type": "null" } ], "description": "The object that contains the fields specific for the address of the account" }, "national_id": { "anyOf": [ { "$ref": "#/components/schemas/NationalId" }, { "type": "null" } ], "description": "The object that contains the fields specific for the national id of the account" }, "created": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created" }, "last_modified": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Modified" } }, "type": "object", "required": [ "reference_id", "account_type" ], "title": "AccountDetails" }, "AccountEntity": { "properties": { "entity_name": { "anyOf": [ { "$ref": "#/components/schemas/EntityName" }, { "type": "null" } ], "description": "The object that contains the entity name fields." }, "entity_localname": { "anyOf": [ { "$ref": "#/components/schemas/EntityName" }, { "type": "null" } ], "description": "The object that contains the entity local name fields." }, "registration_country": { "anyOf": [ { "type": "string", "maxLength": 2 }, { "type": "null" } ], "title": "Registration Country", "description": "Country code of incorporation for the business.", "examples": [ "SG" ] } }, "type": "object", "title": "AccountEntity" }, "AccountFieldUpdate": { "properties": { "field": { "items": { "type": "string" }, "type": "array", "minItems": 1, "title": "Field", "description": "The name of the field to be updated." }, "value": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Value", "description": "The value of the field to be updated to.", "examples": [ "Mark" ] } }, "type": "object", "required": [ "field", "value" ], "title": "AccountFieldUpdate" }, "AccountIndividual": { "properties": { "individual_name": { "anyOf": [ { "$ref": "#/components/schemas/IndividualName" }, { "type": "null" } ], "description": "Object that contains the individual name fields" }, "individual_localname": { "anyOf": [ { "$ref": "#/components/schemas/IndividualName" }, { "type": "null" } ], "description": "Object that contains the individual local name fields" }, "date_of_birth": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Date Of Birth", "description": "Date of birth of the account holder.", "examples": [ "1990-01-01" ] }, "place_of_birth": { "anyOf": [ { "type": "string", "maxLength": 70 }, { "type": "null" } ], "title": "Place Of Birth", "description": "Place of birth of the account holder.", "examples": [ "Singapore, Singapore" ] }, "nationality_country": { "anyOf": [ { "type": "string", "maxLength": 2 }, { "type": "null" } ], "title": "Nationality Country", "description": "Country code of the nationality of the account holder.", "examples": [ "SG" ] }, "residence_country": { "anyOf": [ { "type": "string", "maxLength": 2 }, { "type": "null" } ], "title": "Residence Country", "description": "Country code of the place of residence of the account holder.", "examples": [ "US" ] } }, "type": "object", "title": "AccountIndividual" }, "AccountTypeString": { "type": "string", "enum": [ "individual", "entity" ], "title": "AccountTypeString" }, "Address": { "properties": { "address_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Address Type", "description": "Required if address object is specified. Type of the address, as an IVMS101 addressType code: HOME (residential), BIZZ (business) or GEOG (unspecified). The code is sent verbatim on every outbound travel-rule payload for this account, so GEOG says only that the type was not stated.", "examples": [ "HOME", "BIZZ", "GEOG" ] }, "address_line": { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "null" } ], "title": "Address Line", "description": "Either providing an address_line or including a combination of address_street_no or address_building_name along with address_street_name is required.", "examples": [ "Apt 123" ] }, "address_street_no": { "anyOf": [ { "type": "string", "maxLength": 16 }, { "type": "null" } ], "title": "Address Street No", "description": "Either providing an address_line or including a combination of address_street_no or address_building_name along with address_street_name is required", "examples": [ "456" ] }, "address_street_name": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Address Street Name", "description": "Either providing an address_line or including a combination of address_street_no or address_building_name along with address_street_name is required.", "examples": [ "Elm Street" ] }, "address_building_name": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Address Building Name", "description": "Either providing an address_line or including a combination of address_street_no or address_building_name along with address_street_name is required.", "examples": [ "Building A" ] }, "address_floor": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ], "title": "Address Floor", "description": "Floor number in the building.", "examples": [ "15" ] }, "address_room": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ], "title": "Address Room", "description": "Room number in the building.", "examples": [ "1503" ] }, "address_department": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ], "title": "Address Department", "description": "Department within the address." }, "address_subdepartment": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ], "title": "Address Subdepartment", "description": "Sub-department within the address." }, "address_postbox": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ], "title": "Address Postbox", "description": "Post office box number.", "examples": [ "PO Box 789" ] }, "address_city_location": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ], "title": "Address City Location", "description": "Geographical location of the city.", "examples": [ "Downtown" ] }, "address_city": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ], "title": "Address City", "description": "City of the account holder's address.", "examples": [ "New York" ] }, "address_region": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ], "title": "Address Region", "description": "Region or state of the account holder's address.", "examples": [ "New York" ] }, "address_district": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ], "title": "Address District", "description": "District of the account holder's address.", "examples": [ "Manhattan" ] }, "address_postcode": { "anyOf": [ { "type": "string", "maxLength": 25 }, { "type": "null" } ], "title": "Address Postcode", "description": "Postal code of the account holder's address.", "examples": [ "08012" ] }, "address_country_code": { "anyOf": [ { "type": "string", "maxLength": 2 }, { "type": "null" } ], "title": "Address Country Code", "description": "Country code of the account holder's address.", "examples": [ "US" ] } }, "type": "object", "required": [ "address_type" ], "title": "Address" }, "ApiErrorResponse": { "properties": { "status": { "type": "string", "title": "Status", "default": "error" }, "code": { "type": "integer", "title": "Code", "description": "Duplicates the HTTP status; use `error_code`. Removed in v3." }, "message": { "type": "string", "title": "Message" }, "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Code", "description": "Stable, machine-readable error code, e.g. `auth.unauthenticated`. Additive-only." }, "data": { "anyOf": [ {}, { "type": "null" } ], "title": "Data" } }, "type": "object", "required": [ "code", "message" ], "title": "ApiErrorResponse", "description": "*summary*: Api error response model" }, "ApiFailResponse": { "properties": { "status": { "type": "string", "title": "Status", "default": "fail" }, "message": { "type": "string", "title": "Message" }, "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Code", "description": "Stable, machine-readable error code, e.g. `auth.unauthenticated`. Additive-only." }, "data": { "anyOf": [ {}, { "type": "null" } ], "title": "Data" } }, "type": "object", "required": [ "message" ], "title": "ApiFailResponse", "description": "*summary*: Api fail response model" }, "CustomerFilterType": { "type": "string", "enum": [ "customer", "non-customer", "all" ], "title": "CustomerFilterType", "description": "Filter options for customer type" }, "EntityName": { "properties": { "name_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name Type", "description": "Type of the name. Required if entity_name or entity_localname or individual_name or individual_local_name is specified", "examples": [ "LEGL" ] }, "name_legal": { "type": "string", "maxLength": 100, "title": "Name Legal", "description": "Name of the business. Required if account_type is entity.", "examples": [ "Digital Capital" ] }, "name_business": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Name Business", "description": "Legal name of the business.", "examples": [ "Digital Capital Pte. Ltd." ] } }, "type": "object", "required": [ "name_type", "name_legal" ], "title": "EntityName" }, "IndividualName": { "properties": { "name_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name Type", "description": "Type of the name. Required if entity_name or entity_localname or individual_name or individual_local_name is specified", "examples": [ "LEGL" ] }, "name_first": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Name First", "description": "First name of the account holder.", "examples": [ "John" ] }, "name_middle": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Name Middle", "description": "Middle name of the account holder.", "examples": [ "Robert" ] }, "name_last": { "type": "string", "maxLength": 100, "title": "Name Last", "description": "Last name of the account holder. Required if account_type is individual.", "examples": [ "Doe" ] } }, "type": "object", "required": [ "name_type", "name_last" ], "title": "IndividualName" }, "NationalId": { "properties": { "national_id_type": { "type": "string", "title": "National Id Type", "description": "Required when national_id object is specified. Type of national identification." }, "national_id": { "type": "string", "maxLength": 35, "title": "National Id", "description": "National identification number.", "examples": [ "ABC123456" ] }, "issue_country": { "anyOf": [ { "type": "string", "maxLength": 2 }, { "type": "null" } ], "title": "Issue Country", "description": "Country that issued the national identification.", "examples": [ "US" ] }, "registration_authority": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ], "title": "Registration Authority", "description": "GLEIF Registration Authority code of the register that issued the national identification: `RA` followed by six digits, e.g. `RA000583`. This is the register's code, not the authority's name. Required for entity national IDs other than `LEIX`, and must be omitted for `LEIX`. Case-insensitive; normalised to upper case." } }, "type": "object", "required": [ "national_id_type", "national_id" ], "title": "NationalId" }, "UpdateAccountRequest": { "properties": { "fields": { "items": { "$ref": "#/components/schemas/AccountFieldUpdate" }, "type": "array", "title": "Fields", "description": "An array of the fields to be updated." } }, "type": "object", "required": [ "fields" ], "title": "UpdateAccountRequest" } }, "securitySchemes": { "HTTPBearer": { "type": "http", "scheme": "bearer" } } }, "tags": [ { "name": "Accounts", "description": "Originator/beneficiary account records — entities and individuals." }, { "name": "VASPs", "description": "The VASP directory used to identify counterparty institutions." } ], "servers": [ { "url": "https://dev-api.ospree.io", "description": "Development" } ] }