> For the complete documentation index, see [llms.txt](https://docs.kiiglobal.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kiiglobal.io/docs/kiichain-pay/api-reference/accounts.md). # Accounts ## GetAccountCountries returns the list of countries associated with an account > Set via UpdateAccountCountries — for the full catalog of registered\ > countries use ListCountries instead ```json {"openapi":"3.0.0","info":{"title":"KiiChain Pay Backend","version":"v1"},"tags":[{"description":"Queries (read operations)","name":"AccountsQueryService"}],"servers":[{"description":"Production","url":"https://backend.pay.kiichain.io"},{"description":"Staging","url":"https://backend.pay.staging.kiichain.io"}],"security":[{"ApiKeyAuth":["accounts.kyc.read","accounts.kyc.read:all"]},{"BearerAuth":["accounts.kyc.read","accounts.kyc.read:all"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Send 'Authorization: APIKey ' to authenticate with a API key.","in":"header","name":"Authorization","type":"apiKey"},"BearerAuth":{"flows":{"password":{"scopes":{},"tokenUrl":"https://backend.pay.kiichain.io/users/v1/auth/login"}},"type":"oauth2"}},"schemas":{"v1GetAccountCountriesResponse":{"properties":{"countries":{"items":{"type":"string"},"title":"countries is the list of ISO 3166-1 alpha-3 country codes associated with the account","type":"array"}},"required":["countries"],"title":"GetAccountCountriesResponse is the response for the get-account-countries endpoint","type":"object"},"AppErrorStatus":{"description":"The error envelope this API returns for every non-2xx response. `details` always contains exactly one AppError.","properties":{"code":{"description":"gRPC status code","format":"int32","type":"integer"},"details":{"description":"Always contains exactly one AppError","items":{"$ref":"#/components/schemas/AppError"},"type":"array"},"message":{"description":"Human-readable error message","type":"string"}},"type":"object"},"AppError":{"description":"Structured error detail responded by any non-2xx response.","properties":{"@type":{"description":"Protobuf Any type URL, always \"type.googleapis.com/pay.common.error.v1.AppError\" for this API","type":"string"},"internalCode":{"description":"Internal error code, unique within the module","format":"int32","type":"integer"},"message":{"description":"Human-readable error message","type":"string"},"meta":{"additionalProperties":{"type":"string"},"description":"Additional structured context for the error, if any","type":"object"},"module":{"description":"Module name where the error occurred (e.g. \"accounts\", \"market\")","type":"string"}},"type":"object"}},"responses":{"AppError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorStatus"}}},"description":"An unexpected error response. `details[0]` is always an AppError, see #/components/schemas/AppError"}}},"paths":{"/accounts/v1/accounts/{accountId}/countries":{"get":{"description":"Set via UpdateAccountCountries — for the full catalog of registered\ncountries use ListCountries instead","operationId":"AccountsQueryService_GetAccountCountries","parameters":[{"description":"account_id represents the account identifier","in":"path","name":"accountId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1GetAccountCountriesResponse"}}},"description":"A successful response."},"default":{"$ref":"#/components/responses/AppError"}},"summary":"GetAccountCountries returns the list of countries associated with an account","tags":["AccountsQueryService"]}}}} ``` ## GetUserByAccountId returns the user information for the provided account id > Resolves account\_id to its owning user. Pairs with GetAccountInfo\ > once the user\_id is known ```json {"openapi":"3.0.0","info":{"title":"KiiChain Pay Backend","version":"v1"},"tags":[{"description":"Queries (read operations)","name":"AccountsQueryService"}],"servers":[{"description":"Production","url":"https://backend.pay.kiichain.io"},{"description":"Staging","url":"https://backend.pay.staging.kiichain.io"}],"security":[{"ApiKeyAuth":["users.accounts.read","users.accounts.read:all"]},{"BearerAuth":["users.accounts.read","users.accounts.read:all"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Send 'Authorization: APIKey ' to authenticate with a API key.","in":"header","name":"Authorization","type":"apiKey"},"BearerAuth":{"flows":{"password":{"scopes":{},"tokenUrl":"https://backend.pay.kiichain.io/users/v1/auth/login"}},"type":"oauth2"}},"schemas":{"v1GetUserByAccountIdResponse":{"properties":{"accounts":{"items":{"type":"string"},"title":"accounts contains the list of account IDs the user belongs to","type":"array"},"user":{"$ref":"#/components/schemas/v1User"}},"required":["user","accounts"],"title":"GetUserByAccountIdResponse is the body response structure from the Get user by account id endpoint","type":"object"},"v1User":{"properties":{"admin":{"title":"admin is the boolean flag to know if the user is an admin (has access to the admin panel)","type":"boolean"},"createdAt":{"format":"date-time","title":"created_at is the date when the user was created","type":"string"},"deletedAt":{"format":"date-time","title":"deleted_at is the date when the user was deleted","type":"string"},"displayName":{"title":"display_name is the user display name","type":"string"},"email":{"title":"email is the user email","type":"string"},"emailVerified":{"title":"email_verified indicates whether the user's email has been verified","type":"boolean"},"id":{"title":"id is the user identifier","type":"string"},"isMfaEnabled":{"title":"isMfaEnabled is the boolean flag to enable/disable MFA","type":"boolean"},"language":{"title":"language contains the current user language which will be used on notifications","type":"string"},"lockReason":{"title":"lock_reason is the reason when the user is locked","type":"string"},"locked":{"title":"locked is the boolean flag to lock/unlock the user","type":"boolean"},"passwordChangedAt":{"format":"date-time","title":"password_changed_at is the date when the password was changed","type":"string"},"superAdmin":{"title":"super_admin is the boolean flag to enable/disable super admin permissions","type":"boolean"},"updatedAt":{"format":"date-time","title":"updated_at is the date when the user was updated","type":"string"}},"required":["id","email","displayName","isMfaEnabled","locked","superAdmin","language","createdAt","updatedAt","admin","emailVerified"],"title":"User contains all information with a user","type":"object"},"AppErrorStatus":{"description":"The error envelope this API returns for every non-2xx response. `details` always contains exactly one AppError.","properties":{"code":{"description":"gRPC status code","format":"int32","type":"integer"},"details":{"description":"Always contains exactly one AppError","items":{"$ref":"#/components/schemas/AppError"},"type":"array"},"message":{"description":"Human-readable error message","type":"string"}},"type":"object"},"AppError":{"description":"Structured error detail responded by any non-2xx response.","properties":{"@type":{"description":"Protobuf Any type URL, always \"type.googleapis.com/pay.common.error.v1.AppError\" for this API","type":"string"},"internalCode":{"description":"Internal error code, unique within the module","format":"int32","type":"integer"},"message":{"description":"Human-readable error message","type":"string"},"meta":{"additionalProperties":{"type":"string"},"description":"Additional structured context for the error, if any","type":"object"},"module":{"description":"Module name where the error occurred (e.g. \"accounts\", \"market\")","type":"string"}},"type":"object"}},"responses":{"AppError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorStatus"}}},"description":"An unexpected error response. `details[0]` is always an AppError, see #/components/schemas/AppError"}}},"paths":{"/accounts/v1/accounts/{accountId}/user":{"get":{"description":"Resolves account_id to its owning user. Pairs with GetAccountInfo\nonce the user_id is known","operationId":"AccountsQueryService_GetUserByAccountId","parameters":[{"description":"account_id represents the account identifier","in":"path","name":"accountId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1GetUserByAccountIdResponse"}}},"description":"A successful response."},"default":{"$ref":"#/components/responses/AppError"}},"summary":"GetUserByAccountId returns the user information for the provided account id","tags":["AccountsQueryService"]}}}} ``` ## ListCountries returns all countries registered in the platform > The full reference for countries, not scoped to any\ > account — see GetAccountCountries for a specific account's countries ```json {"openapi":"3.0.0","info":{"title":"KiiChain Pay Backend","version":"v1"},"tags":[{"description":"Queries (read operations)","name":"AccountsQueryService"}],"servers":[{"description":"Production","url":"https://backend.pay.kiichain.io"},{"description":"Staging","url":"https://backend.pay.staging.kiichain.io"}],"security":[{"ApiKeyAuth":["accounts.kyc.read"]},{"BearerAuth":["accounts.kyc.read"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Send 'Authorization: APIKey ' to authenticate with a API key.","in":"header","name":"Authorization","type":"apiKey"},"BearerAuth":{"flows":{"password":{"scopes":{},"tokenUrl":"https://backend.pay.kiichain.io/users/v1/auth/login"}},"type":"oauth2"}},"schemas":{"v1ListCountriesResponse":{"properties":{"countries":{"items":{"$ref":"#/components/schemas/v1Country"},"title":"countries is the list of all registered countries","type":"array"}},"required":["countries"],"title":"ListCountriesResponse is the response for the list-countries endpoint","type":"object"},"v1Country":{"properties":{"code":{"title":"code is the ISO 3166-1 alpha-3 country code","type":"string"},"name":{"title":"name is the human-readable country name","type":"string"}},"required":["code","name"],"title":"Country represents a country registered in the platform","type":"object"},"AppErrorStatus":{"description":"The error envelope this API returns for every non-2xx response. `details` always contains exactly one AppError.","properties":{"code":{"description":"gRPC status code","format":"int32","type":"integer"},"details":{"description":"Always contains exactly one AppError","items":{"$ref":"#/components/schemas/AppError"},"type":"array"},"message":{"description":"Human-readable error message","type":"string"}},"type":"object"},"AppError":{"description":"Structured error detail responded by any non-2xx response.","properties":{"@type":{"description":"Protobuf Any type URL, always \"type.googleapis.com/pay.common.error.v1.AppError\" for this API","type":"string"},"internalCode":{"description":"Internal error code, unique within the module","format":"int32","type":"integer"},"message":{"description":"Human-readable error message","type":"string"},"meta":{"additionalProperties":{"type":"string"},"description":"Additional structured context for the error, if any","type":"object"},"module":{"description":"Module name where the error occurred (e.g. \"accounts\", \"market\")","type":"string"}},"type":"object"}},"responses":{"AppError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorStatus"}}},"description":"An unexpected error response. `details[0]` is always an AppError, see #/components/schemas/AppError"}}},"paths":{"/accounts/v1/countries":{"get":{"description":"The full reference for countries, not scoped to any\naccount — see GetAccountCountries for a specific account's countries","operationId":"AccountsQueryService_ListCountries","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListCountriesResponse"}}},"description":"A successful response."},"default":{"$ref":"#/components/responses/AppError"}},"summary":"ListCountries returns all countries registered in the platform","tags":["AccountsQueryService"]}}}} ``` ## ListAccountLevels returns the existing levels for accounts > Supports optional filtering by account\_type and level ```json {"openapi":"3.0.0","info":{"title":"KiiChain Pay Backend","version":"v1"},"tags":[{"description":"Queries (read operations)","name":"AccountsQueryService"}],"servers":[{"description":"Production","url":"https://backend.pay.kiichain.io"},{"description":"Staging","url":"https://backend.pay.staging.kiichain.io"}],"security":[{"ApiKeyAuth":["users.accounts.read"]},{"BearerAuth":["users.accounts.read"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Send 'Authorization: APIKey ' to authenticate with a API key.","in":"header","name":"Authorization","type":"apiKey"},"BearerAuth":{"flows":{"password":{"scopes":{},"tokenUrl":"https://backend.pay.kiichain.io/users/v1/auth/login"}},"type":"oauth2"}},"schemas":{"v1ListAccountLevelsResponse":{"properties":{"levels":{"items":{"$ref":"#/components/schemas/v1AccountLevel"},"title":"levels contains the array of account levels","type":"array"}},"required":["levels"],"title":"ListAccountLevelsResponse is the body response structure from the List account levels endpoint","type":"object"},"v1AccountLevel":{"properties":{"accountType":{"title":"account_type defines if the level is for individual or company accounts","type":"string"},"description":{"title":"description defines the description of the level","type":"string"},"id":{"title":"id represents the account level identifier","type":"string"},"level":{"format":"int32","title":"level defines the level of the account","type":"integer"},"name":{"title":"name defines the name of the level","type":"string"}},"required":["id","accountType","level","name","description"],"title":"AccountLevel defines the type of account level","type":"object"},"AppErrorStatus":{"description":"The error envelope this API returns for every non-2xx response. `details` always contains exactly one AppError.","properties":{"code":{"description":"gRPC status code","format":"int32","type":"integer"},"details":{"description":"Always contains exactly one AppError","items":{"$ref":"#/components/schemas/AppError"},"type":"array"},"message":{"description":"Human-readable error message","type":"string"}},"type":"object"},"AppError":{"description":"Structured error detail responded by any non-2xx response.","properties":{"@type":{"description":"Protobuf Any type URL, always \"type.googleapis.com/pay.common.error.v1.AppError\" for this API","type":"string"},"internalCode":{"description":"Internal error code, unique within the module","format":"int32","type":"integer"},"message":{"description":"Human-readable error message","type":"string"},"meta":{"additionalProperties":{"type":"string"},"description":"Additional structured context for the error, if any","type":"object"},"module":{"description":"Module name where the error occurred (e.g. \"accounts\", \"market\")","type":"string"}},"type":"object"}},"responses":{"AppError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorStatus"}}},"description":"An unexpected error response. `details[0]` is always an AppError, see #/components/schemas/AppError"}}},"paths":{"/accounts/v1/levels":{"get":{"description":"Supports optional filtering by account_type and level","operationId":"AccountsQueryService_ListAccountLevels","parameters":[{"description":"account_type is an optional query parameter to filter leves by account type","in":"query","name":"accountType","required":false,"schema":{"type":"string"}},{"description":"level is an optional query parameter to filter leves by level","in":"query","name":"level","required":false,"schema":{"format":"int32","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListAccountLevelsResponse"}}},"description":"A successful response."},"default":{"$ref":"#/components/responses/AppError"}},"summary":"ListAccountLevels returns the existing levels for accounts","tags":["AccountsQueryService"]}}}} ``` ## ListAccountLimits returns the existing limits for accounts > The configured defaults per level/action, not a specific account's\ > effective limits — use GetAccountLimits for that ```json {"openapi":"3.0.0","info":{"title":"KiiChain Pay Backend","version":"v1"},"tags":[{"description":"Queries (read operations)","name":"AccountsQueryService"}],"servers":[{"description":"Production","url":"https://backend.pay.kiichain.io"},{"description":"Staging","url":"https://backend.pay.staging.kiichain.io"}],"security":[{"ApiKeyAuth":["users.accounts.read"]},{"BearerAuth":["users.accounts.read"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Send 'Authorization: APIKey ' to authenticate with a API key.","in":"header","name":"Authorization","type":"apiKey"},"BearerAuth":{"flows":{"password":{"scopes":{},"tokenUrl":"https://backend.pay.kiichain.io/users/v1/auth/login"}},"type":"oauth2"}},"schemas":{"v1ListAccountLimitsResponse":{"properties":{"limits":{"items":{"$ref":"#/components/schemas/v1AccountLimit"},"title":"limits contains the account limits information","type":"array"}},"required":["limits"],"title":"ListAccountLimitsResponse is the body response structure from the List account limits endpoint","type":"object"},"v1AccountLimit":{"properties":{"accountType":{"title":"account_type defines if the limits are for individual or company accounts","type":"string"},"active":{"title":"active defines if the override is active or not","type":"boolean"},"amountUsd":{"title":"amount_usd defines the amount of the limit in USD","type":"string"},"description":{"title":"description defines the description of the level","type":"string"},"id":{"title":"id represents the limit identifier","type":"string"},"level":{"format":"int32","title":"level defines the level of the account","type":"integer"},"limitAction":{"title":"limit_action defines the action (withdrawal | deposit | swap)","type":"string"},"name":{"title":"name defines the name of the level","type":"string"},"periodDays":{"format":"int32","title":"period_days defines the period of the limit in days","type":"integer"}},"required":["id","accountType","level","name","limitAction","amountUsd","periodDays","active"],"title":"AccountLimit defines the type of account limits","type":"object"},"AppErrorStatus":{"description":"The error envelope this API returns for every non-2xx response. `details` always contains exactly one AppError.","properties":{"code":{"description":"gRPC status code","format":"int32","type":"integer"},"details":{"description":"Always contains exactly one AppError","items":{"$ref":"#/components/schemas/AppError"},"type":"array"},"message":{"description":"Human-readable error message","type":"string"}},"type":"object"},"AppError":{"description":"Structured error detail responded by any non-2xx response.","properties":{"@type":{"description":"Protobuf Any type URL, always \"type.googleapis.com/pay.common.error.v1.AppError\" for this API","type":"string"},"internalCode":{"description":"Internal error code, unique within the module","format":"int32","type":"integer"},"message":{"description":"Human-readable error message","type":"string"},"meta":{"additionalProperties":{"type":"string"},"description":"Additional structured context for the error, if any","type":"object"},"module":{"description":"Module name where the error occurred (e.g. \"accounts\", \"market\")","type":"string"}},"type":"object"}},"responses":{"AppError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorStatus"}}},"description":"An unexpected error response. `details[0]` is always an AppError, see #/components/schemas/AppError"}}},"paths":{"/accounts/v1/limits":{"get":{"description":"The configured defaults per level/action, not a specific account's\neffective limits — use GetAccountLimits for that","operationId":"AccountsQueryService_ListAccountLimits","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListAccountLimitsResponse"}}},"description":"A successful response."},"default":{"$ref":"#/components/responses/AppError"}},"summary":"ListAccountLimits returns the existing limits for accounts","tags":["AccountsQueryService"]}}}} ``` ## ListAccountLimitOverrides returns all the overrides information for the provided account id > List of overrides, not scoped to a single account. Includes each override's reason and active status ```json {"openapi":"3.0.0","info":{"title":"KiiChain Pay Backend","version":"v1"},"tags":[{"description":"Queries (read operations)","name":"AccountsQueryService"}],"servers":[{"description":"Production","url":"https://backend.pay.kiichain.io"},{"description":"Staging","url":"https://backend.pay.staging.kiichain.io"}],"security":[{"ApiKeyAuth":["users.accounts.read"]},{"BearerAuth":["users.accounts.read"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Send 'Authorization: APIKey ' to authenticate with a API key.","in":"header","name":"Authorization","type":"apiKey"},"BearerAuth":{"flows":{"password":{"scopes":{},"tokenUrl":"https://backend.pay.kiichain.io/users/v1/auth/login"}},"type":"oauth2"}},"schemas":{"v1ListAccountLimitOverridesResponse":{"properties":{"overrides":{"items":{"$ref":"#/components/schemas/v1AccountLimitOverride"},"title":"overrides contains the account limit overrides information","type":"array"}},"required":["overrides"],"title":"ListAccountLimitOverridesResponse is the body response structure from the Get account limit overrides endpoint","type":"object"},"v1AccountLimitOverride":{"properties":{"accountId":{"title":"account_id represents the account identifier","type":"string"},"active":{"title":"active defines if the override is active or not","type":"boolean"},"amountUsd":{"title":"amount_usd defines the amount of the limit in USD","type":"string"},"id":{"title":"id represents the override identifier","type":"string"},"limitAction":{"title":"limit_action defines the action (withdrawal | deposit | swap)","type":"string"},"periodDays":{"format":"int32","title":"period_days defines the period of the limit in days","type":"integer"},"reason":{"title":"reason defines the reason for the override","type":"string"}},"required":["id","accountId","limitAction","amountUsd","reason","periodDays","active"],"title":"AccountLimitOverride defines the type of account limit override","type":"object"},"AppErrorStatus":{"description":"The error envelope this API returns for every non-2xx response. `details` always contains exactly one AppError.","properties":{"code":{"description":"gRPC status code","format":"int32","type":"integer"},"details":{"description":"Always contains exactly one AppError","items":{"$ref":"#/components/schemas/AppError"},"type":"array"},"message":{"description":"Human-readable error message","type":"string"}},"type":"object"},"AppError":{"description":"Structured error detail responded by any non-2xx response.","properties":{"@type":{"description":"Protobuf Any type URL, always \"type.googleapis.com/pay.common.error.v1.AppError\" for this API","type":"string"},"internalCode":{"description":"Internal error code, unique within the module","format":"int32","type":"integer"},"message":{"description":"Human-readable error message","type":"string"},"meta":{"additionalProperties":{"type":"string"},"description":"Additional structured context for the error, if any","type":"object"},"module":{"description":"Module name where the error occurred (e.g. \"accounts\", \"market\")","type":"string"}},"type":"object"}},"responses":{"AppError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorStatus"}}},"description":"An unexpected error response. `details[0]` is always an AppError, see #/components/schemas/AppError"}}},"paths":{"/accounts/v1/limits/overrides":{"get":{"description":"List of overrides, not scoped to a single account. Includes each override's reason and active status","operationId":"AccountsQueryService_ListAccountLimitOverrides","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListAccountLimitOverridesResponse"}}},"description":"A successful response."},"default":{"$ref":"#/components/responses/AppError"}},"summary":"ListAccountLimitOverrides returns all the overrides information for the provided account id","tags":["AccountsQueryService"]}}}} ``` ## GetAllRailSchemas handle the request to get all rail schemas > Each schema describes the payload shape a rail\_code/rail\_version expects\ > Use this to build the payload for RegisterWithdrawalDestination.\ > Country optionally filters to rails available in that country ```json {"openapi":"3.0.0","info":{"title":"KiiChain Pay Backend","version":"v1"},"tags":[{"description":"Queries (read operations)","name":"AccountsQueryService"}],"servers":[{"description":"Production","url":"https://backend.pay.kiichain.io"},{"description":"Staging","url":"https://backend.pay.staging.kiichain.io"}],"security":[{"ApiKeyAuth":["accounts.withdrawal_destination.read"]},{"BearerAuth":["accounts.withdrawal_destination.read"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Send 'Authorization: APIKey ' to authenticate with a API key.","in":"header","name":"Authorization","type":"apiKey"},"BearerAuth":{"flows":{"password":{"scopes":{},"tokenUrl":"https://backend.pay.kiichain.io/users/v1/auth/login"}},"type":"oauth2"}},"schemas":{"v1GetAllRailSchemasResponse":{"properties":{"schemas":{"items":{"$ref":"#/components/schemas/v1RailSchema"},"title":"schemas represents the rail schemas","type":"array"}},"required":["schemas"],"title":"GetAllRailSchemasResponse is the body response structure from the GetAllRailSchemas endpoint","type":"object"},"v1RailSchema":{"properties":{"country":{"title":"country represents the country associated to the rail schema","type":"string"},"railCode":{"title":"rail_code represents the rail code","type":"string"},"railVersion":{"format":"int32","title":"rail_version represents the rail version","type":"integer"},"schema":{"$ref":"#/components/schemas/typesV1Schema"},"type":{"title":"type represents the rail type (bank | wallet)","type":"string"}},"required":["railCode","railVersion","country","type","schema"],"title":"RailSchema is the structure of a rail schema","type":"object"},"typesV1Schema":{"properties":{"fields":{"items":{"$ref":"#/components/schemas/v1FieldSchema"},"title":"fields are the fields that the schema contains","type":"array"},"title":{"title":"title is the name of the schema","type":"string"}},"required":["title","fields"],"title":"Schema defines the Schema type used to returns schemas on Rails and providers","type":"object"},"v1FieldSchema":{"properties":{"name":{"title":"name is the name of the field required by the backend","type":"string"},"optional":{"title":"optional contains the flag that determines if the field is optional or not","type":"boolean"},"options":{"items":{"type":"string"},"title":"options contains the available options if type is an enum","type":"array"},"pattern":{"title":"pattern contains the regex expresion to evaluate the field","type":"string"},"type":{"title":"type contains the type of the field","type":"string"}},"required":["name","type","optional"],"title":"FieldSchema describe the field on the schema and its properties","type":"object"},"AppErrorStatus":{"description":"The error envelope this API returns for every non-2xx response. `details` always contains exactly one AppError.","properties":{"code":{"description":"gRPC status code","format":"int32","type":"integer"},"details":{"description":"Always contains exactly one AppError","items":{"$ref":"#/components/schemas/AppError"},"type":"array"},"message":{"description":"Human-readable error message","type":"string"}},"type":"object"},"AppError":{"description":"Structured error detail responded by any non-2xx response.","properties":{"@type":{"description":"Protobuf Any type URL, always \"type.googleapis.com/pay.common.error.v1.AppError\" for this API","type":"string"},"internalCode":{"description":"Internal error code, unique within the module","format":"int32","type":"integer"},"message":{"description":"Human-readable error message","type":"string"},"meta":{"additionalProperties":{"type":"string"},"description":"Additional structured context for the error, if any","type":"object"},"module":{"description":"Module name where the error occurred (e.g. \"accounts\", \"market\")","type":"string"}},"type":"object"}},"responses":{"AppError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorStatus"}}},"description":"An unexpected error response. `details[0]` is always an AppError, see #/components/schemas/AppError"}}},"paths":{"/accounts/v1/rails/schemas":{"get":{"description":"Each schema describes the payload shape a rail_code/rail_version expects\nUse this to build the payload for RegisterWithdrawalDestination.\nCountry optionally filters to rails available in that country","operationId":"AccountsQueryService_GetAllRailSchemas","parameters":[{"description":"country represents the country associated to the rail schemas","in":"query","name":"country","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1GetAllRailSchemasResponse"}}},"description":"A successful response."},"default":{"$ref":"#/components/responses/AppError"}},"summary":"GetAllRailSchemas handle the request to get all rail schemas","tags":["AccountsQueryService"]}}}} ``` ## GetUserAccounts returns all accounts associated to the provided user\_id > Full account objects (KYC, wallets) for every account the user holds\ > for a single account use GetAccountInfo instead ```json {"openapi":"3.0.0","info":{"title":"KiiChain Pay Backend","version":"v1"},"tags":[{"description":"Queries (read operations)","name":"AccountsQueryService"}],"servers":[{"description":"Production","url":"https://backend.pay.kiichain.io"},{"description":"Staging","url":"https://backend.pay.staging.kiichain.io"}],"security":[{"ApiKeyAuth":["users.accounts.read","users.accounts.read:all"]},{"BearerAuth":["users.accounts.read","users.accounts.read:all"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Send 'Authorization: APIKey ' to authenticate with a API key.","in":"header","name":"Authorization","type":"apiKey"},"BearerAuth":{"flows":{"password":{"scopes":{},"tokenUrl":"https://backend.pay.kiichain.io/users/v1/auth/login"}},"type":"oauth2"}},"schemas":{"v1GetUserAccountsResponse":{"properties":{"accounts":{"items":{"$ref":"#/components/schemas/v1Account"},"title":"accounts contains the array of accounts associated to the user","type":"array"}},"required":["accounts"],"title":"GetUserAccountsResponse is the body response structure from the Get user accounts endpoint","type":"object"},"v1Account":{"properties":{"accountName":{"title":"account_name is the name of the account","type":"string"},"accountType":{"title":"account_type is the type of the account","type":"string"},"countries":{"items":{"type":"string"},"title":"countries is the list of countries associated to the account, in ISO 3166-1 alpha-3 format","type":"array"},"createdAt":{"format":"date-time","title":"created_at is the date when the account was created","type":"string"},"deletedAt":{"format":"date-time","title":"deleted_at is the date when the account was deleted","type":"string"},"id":{"title":"id is the account identifier","type":"string"},"kycInfo":{"$ref":"#/components/schemas/v1KycInfo"},"privyId":{"title":"privy_id is the identifier of the account on Privy, which is the Wallet provider used by default","type":"string"},"updatedAt":{"format":"date-time","title":"updated_at is the date when the account was updated","type":"string"},"userId":{"title":"account_name is the user-assigned name of the account","type":"string"},"wallets":{"items":{"$ref":"#/components/schemas/v1Wallet"},"title":"wallets is the information about the wallets associated to the account","type":"array"}},"required":["id","userId","accountName","accountType","wallets","kycInfo","createdAt","updatedAt","privyId"],"title":"Account contains all information with a account","type":"object"},"v1KycInfo":{"properties":{"level":{"format":"int32","title":"level is the name of the KYC level approved","type":"integer"},"provider":{"title":"provider is the KYC provider name","type":"string"},"requestedAt":{"format":"date-time","title":"requested_at is the date when the KYC was requested","type":"string"},"status":{"title":"status is the KYC status","type":"string"},"verifiedAt":{"format":"date-time","title":"verified_at is the date when the KYC was verified","type":"string"}},"required":["provider","level","status","requestedAt","verifiedAt"],"title":"KycInfo contains the KYC information per account","type":"object"},"v1Wallet":{"properties":{"address":{"title":"address is the unique wallet address","type":"string"},"chainType":{"title":"chain_type is which chain is using this wallet","type":"string"},"id":{"title":"id is the wallet identifier","type":"string"}},"required":["id","address","chainType"],"title":"Wallet contains all information about a wallet","type":"object"},"AppErrorStatus":{"description":"The error envelope this API returns for every non-2xx response. `details` always contains exactly one AppError.","properties":{"code":{"description":"gRPC status code","format":"int32","type":"integer"},"details":{"description":"Always contains exactly one AppError","items":{"$ref":"#/components/schemas/AppError"},"type":"array"},"message":{"description":"Human-readable error message","type":"string"}},"type":"object"},"AppError":{"description":"Structured error detail responded by any non-2xx response.","properties":{"@type":{"description":"Protobuf Any type URL, always \"type.googleapis.com/pay.common.error.v1.AppError\" for this API","type":"string"},"internalCode":{"description":"Internal error code, unique within the module","format":"int32","type":"integer"},"message":{"description":"Human-readable error message","type":"string"},"meta":{"additionalProperties":{"type":"string"},"description":"Additional structured context for the error, if any","type":"object"},"module":{"description":"Module name where the error occurred (e.g. \"accounts\", \"market\")","type":"string"}},"type":"object"}},"responses":{"AppError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorStatus"}}},"description":"An unexpected error response. `details[0]` is always an AppError, see #/components/schemas/AppError"}}},"paths":{"/accounts/v1/users/{userId}/accounts":{"get":{"description":"Full account objects (KYC, wallets) for every account the user holds\nfor a single account use GetAccountInfo instead","operationId":"AccountsQueryService_GetUserAccounts","parameters":[{"description":"user_id represents the user identifier","in":"path","name":"userId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1GetUserAccountsResponse"}}},"description":"A successful response."},"default":{"$ref":"#/components/responses/AppError"}},"summary":"GetUserAccounts returns all accounts associated to the provided user_id","tags":["AccountsQueryService"]}}}} ``` ## GetAccountInfo returns the account information for the provided account id > Scoped under a user\_id. Use GetUserByAccountId if only the account\_id\ > is known and the owning user needs to be resolved first ```json {"openapi":"3.0.0","info":{"title":"KiiChain Pay Backend","version":"v1"},"tags":[{"description":"Queries (read operations)","name":"AccountsQueryService"}],"servers":[{"description":"Production","url":"https://backend.pay.kiichain.io"},{"description":"Staging","url":"https://backend.pay.staging.kiichain.io"}],"security":[{"ApiKeyAuth":["users.accounts.read","users.accounts.read:all"]},{"BearerAuth":["users.accounts.read","users.accounts.read:all"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Send 'Authorization: APIKey ' to authenticate with a API key.","in":"header","name":"Authorization","type":"apiKey"},"BearerAuth":{"flows":{"password":{"scopes":{},"tokenUrl":"https://backend.pay.kiichain.io/users/v1/auth/login"}},"type":"oauth2"}},"schemas":{"v1GetAccountInfoResponse":{"properties":{"account":{"$ref":"#/components/schemas/v1Account"}},"required":["account"],"title":"GetAccountInfoResponse is the body response structure from the Get account info endpoints","type":"object"},"v1Account":{"properties":{"accountName":{"title":"account_name is the name of the account","type":"string"},"accountType":{"title":"account_type is the type of the account","type":"string"},"countries":{"items":{"type":"string"},"title":"countries is the list of countries associated to the account, in ISO 3166-1 alpha-3 format","type":"array"},"createdAt":{"format":"date-time","title":"created_at is the date when the account was created","type":"string"},"deletedAt":{"format":"date-time","title":"deleted_at is the date when the account was deleted","type":"string"},"id":{"title":"id is the account identifier","type":"string"},"kycInfo":{"$ref":"#/components/schemas/v1KycInfo"},"privyId":{"title":"privy_id is the identifier of the account on Privy, which is the Wallet provider used by default","type":"string"},"updatedAt":{"format":"date-time","title":"updated_at is the date when the account was updated","type":"string"},"userId":{"title":"account_name is the user-assigned name of the account","type":"string"},"wallets":{"items":{"$ref":"#/components/schemas/v1Wallet"},"title":"wallets is the information about the wallets associated to the account","type":"array"}},"required":["id","userId","accountName","accountType","wallets","kycInfo","createdAt","updatedAt","privyId"],"title":"Account contains all information with a account","type":"object"},"v1KycInfo":{"properties":{"level":{"format":"int32","title":"level is the name of the KYC level approved","type":"integer"},"provider":{"title":"provider is the KYC provider name","type":"string"},"requestedAt":{"format":"date-time","title":"requested_at is the date when the KYC was requested","type":"string"},"status":{"title":"status is the KYC status","type":"string"},"verifiedAt":{"format":"date-time","title":"verified_at is the date when the KYC was verified","type":"string"}},"required":["provider","level","status","requestedAt","verifiedAt"],"title":"KycInfo contains the KYC information per account","type":"object"},"v1Wallet":{"properties":{"address":{"title":"address is the unique wallet address","type":"string"},"chainType":{"title":"chain_type is which chain is using this wallet","type":"string"},"id":{"title":"id is the wallet identifier","type":"string"}},"required":["id","address","chainType"],"title":"Wallet contains all information about a wallet","type":"object"},"AppErrorStatus":{"description":"The error envelope this API returns for every non-2xx response. `details` always contains exactly one AppError.","properties":{"code":{"description":"gRPC status code","format":"int32","type":"integer"},"details":{"description":"Always contains exactly one AppError","items":{"$ref":"#/components/schemas/AppError"},"type":"array"},"message":{"description":"Human-readable error message","type":"string"}},"type":"object"},"AppError":{"description":"Structured error detail responded by any non-2xx response.","properties":{"@type":{"description":"Protobuf Any type URL, always \"type.googleapis.com/pay.common.error.v1.AppError\" for this API","type":"string"},"internalCode":{"description":"Internal error code, unique within the module","format":"int32","type":"integer"},"message":{"description":"Human-readable error message","type":"string"},"meta":{"additionalProperties":{"type":"string"},"description":"Additional structured context for the error, if any","type":"object"},"module":{"description":"Module name where the error occurred (e.g. \"accounts\", \"market\")","type":"string"}},"type":"object"}},"responses":{"AppError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorStatus"}}},"description":"An unexpected error response. `details[0]` is always an AppError, see #/components/schemas/AppError"}}},"paths":{"/accounts/v1/users/{userId}/accounts/{accountId}":{"get":{"description":"Scoped under a user_id. Use GetUserByAccountId if only the account_id\nis known and the owning user needs to be resolved first","operationId":"AccountsQueryService_GetAccountInfo","parameters":[{"description":"user_id represents the user identifier","in":"path","name":"userId","required":true,"schema":{"type":"string"}},{"description":"account_id represents the account identifier","in":"path","name":"accountId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1GetAccountInfoResponse"}}},"description":"A successful response."},"default":{"$ref":"#/components/responses/AppError"}},"summary":"GetAccountInfo returns the account information for the provided account id","tags":["AccountsQueryService"]}}}} ``` ## GetAccountLimits returns the limits information for the provided account id > Merges the level's default limits with any active per-account overrides,\ > and includes current usage ```json {"openapi":"3.0.0","info":{"title":"KiiChain Pay Backend","version":"v1"},"tags":[{"description":"Queries (read operations)","name":"AccountsQueryService"}],"servers":[{"description":"Production","url":"https://backend.pay.kiichain.io"},{"description":"Staging","url":"https://backend.pay.staging.kiichain.io"}],"security":[{"ApiKeyAuth":["users.accounts.read","users.accounts.read:all"]},{"BearerAuth":["users.accounts.read","users.accounts.read:all"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Send 'Authorization: APIKey ' to authenticate with a API key.","in":"header","name":"Authorization","type":"apiKey"},"BearerAuth":{"flows":{"password":{"scopes":{},"tokenUrl":"https://backend.pay.kiichain.io/users/v1/auth/login"}},"type":"oauth2"}},"schemas":{"v1GetAccountLimitsResponse":{"properties":{"limits":{"items":{"$ref":"#/components/schemas/v1AccountLimitWithUsage"},"title":"limits contains the account limits information","type":"array"}},"required":["limits"],"title":"GetAccountLimitsResponse is the body response structure from the Get account limits endpoint","type":"object"},"v1AccountLimitWithUsage":{"properties":{"amountUsd":{"title":"amount_usd defines the amount of the limit in USD","type":"string"},"id":{"title":"id represents the limit identifier","type":"string"},"level":{"format":"int32","title":"level defines the level of the account","type":"integer"},"limitAction":{"title":"limit_action defines the action (withdrawal | deposit | swap)","type":"string"},"name":{"title":"name defines the name of the level","type":"string"},"periodDays":{"format":"int32","title":"period_days defines the period of the limit in days","type":"integer"},"usedAmountUsd":{"title":"used_amount_usd defines the used amount of the limit in USD","type":"string"}},"required":["id","level","name","limitAction","amountUsd","usedAmountUsd","periodDays"],"title":"AccountLimitWithUsage defines the type of account limit with usage information","type":"object"},"AppErrorStatus":{"description":"The error envelope this API returns for every non-2xx response. `details` always contains exactly one AppError.","properties":{"code":{"description":"gRPC status code","format":"int32","type":"integer"},"details":{"description":"Always contains exactly one AppError","items":{"$ref":"#/components/schemas/AppError"},"type":"array"},"message":{"description":"Human-readable error message","type":"string"}},"type":"object"},"AppError":{"description":"Structured error detail responded by any non-2xx response.","properties":{"@type":{"description":"Protobuf Any type URL, always \"type.googleapis.com/pay.common.error.v1.AppError\" for this API","type":"string"},"internalCode":{"description":"Internal error code, unique within the module","format":"int32","type":"integer"},"message":{"description":"Human-readable error message","type":"string"},"meta":{"additionalProperties":{"type":"string"},"description":"Additional structured context for the error, if any","type":"object"},"module":{"description":"Module name where the error occurred (e.g. \"accounts\", \"market\")","type":"string"}},"type":"object"}},"responses":{"AppError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorStatus"}}},"description":"An unexpected error response. `details[0]` is always an AppError, see #/components/schemas/AppError"}}},"paths":{"/accounts/v1/users/{userId}/accounts/{accountId}/limits":{"get":{"description":"Merges the level's default limits with any active per-account overrides,\nand includes current usage","operationId":"AccountsQueryService_GetAccountLimits","parameters":[{"description":"user_id represents the user identifier","in":"path","name":"userId","required":true,"schema":{"type":"string"}},{"description":"account_id represents the account identifier","in":"path","name":"accountId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1GetAccountLimitsResponse"}}},"description":"A successful response."},"default":{"$ref":"#/components/responses/AppError"}},"summary":"GetAccountLimits returns the limits information for the provided account id","tags":["AccountsQueryService"]}}}} ``` ## GetAccountWithdrawalDestinations handle the request to get all withdrawal destinations for an account > Includes destinations in every status (pending and confirmed). Filter\ > client-side if only confirmed ones are needed. Name optionally does a\ > case-insensitive partial match ```json {"openapi":"3.0.0","info":{"title":"KiiChain Pay Backend","version":"v1"},"tags":[{"description":"Queries (read operations)","name":"AccountsQueryService"}],"servers":[{"description":"Production","url":"https://backend.pay.kiichain.io"},{"description":"Staging","url":"https://backend.pay.staging.kiichain.io"}],"security":[{"ApiKeyAuth":["accounts.withdrawal_destination.read"]},{"BearerAuth":["accounts.withdrawal_destination.read"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Send 'Authorization: APIKey ' to authenticate with a API key.","in":"header","name":"Authorization","type":"apiKey"},"BearerAuth":{"flows":{"password":{"scopes":{},"tokenUrl":"https://backend.pay.kiichain.io/users/v1/auth/login"}},"type":"oauth2"}},"schemas":{"v1GetAccountWithdrawalDestinationsResponse":{"properties":{"destinations":{"items":{"$ref":"#/components/schemas/v1WithdrawalDestination"},"title":"destinations represents the withdrawal destinations","type":"array"}},"required":["destinations"],"title":"GetWithdrawalDestinationsResponse is the body response structure from the GetWithdrawalDestinations endpoint","type":"object"},"v1WithdrawalDestination":{"properties":{"accountId":{"title":"account_id represents the account associated to the withdrawal destination","type":"string"},"country":{"title":"country returns the country associated to the destination","type":"string"},"createdAt":{"format":"date-time","title":"created_at is the date when the withdrawal destination was created","type":"string"},"id":{"title":"id represents the withdrawal destination identifier on our database","type":"string"},"identifier":{"title":"identifier represents a value that identifier the destination from others\n(e.g on bank transfer is the account number)","type":"string"},"name":{"title":"name is the user-defined label for this destination","type":"string"},"payload":{"title":"Rail-specific payload (dynamic schema)","type":"object"},"railCode":{"title":"rail_code represents the rail code","type":"string"},"railVersion":{"format":"int32","title":"rail_version represents the rail version","type":"integer"},"status":{"title":"status represents the withdrawal destination status (if has been verified or not)","type":"string"},"type":{"title":"type contains the destination type (wallet | bank)","type":"string"},"updatedAt":{"format":"date-time","title":"updated_at is the date when the withdrawal destination was updated","type":"string"}},"required":["id","accountId","railCode","railVersion","payload","country","type","status","identifier","createdAt","name"],"title":"WithdrawalDestination represents a withdrawal destination","type":"object"},"AppErrorStatus":{"description":"The error envelope this API returns for every non-2xx response. `details` always contains exactly one AppError.","properties":{"code":{"description":"gRPC status code","format":"int32","type":"integer"},"details":{"description":"Always contains exactly one AppError","items":{"$ref":"#/components/schemas/AppError"},"type":"array"},"message":{"description":"Human-readable error message","type":"string"}},"type":"object"},"AppError":{"description":"Structured error detail responded by any non-2xx response.","properties":{"@type":{"description":"Protobuf Any type URL, always \"type.googleapis.com/pay.common.error.v1.AppError\" for this API","type":"string"},"internalCode":{"description":"Internal error code, unique within the module","format":"int32","type":"integer"},"message":{"description":"Human-readable error message","type":"string"},"meta":{"additionalProperties":{"type":"string"},"description":"Additional structured context for the error, if any","type":"object"},"module":{"description":"Module name where the error occurred (e.g. \"accounts\", \"market\")","type":"string"}},"type":"object"}},"responses":{"AppError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorStatus"}}},"description":"An unexpected error response. `details[0]` is always an AppError, see #/components/schemas/AppError"}}},"paths":{"/accounts/v1/users/{userId}/accounts/{accountId}/withdrawal_destinations":{"get":{"description":"Includes destinations in every status (pending and confirmed). Filter\nclient-side if only confirmed ones are needed. Name optionally does a\ncase-insensitive partial match","operationId":"AccountsQueryService_GetAccountWithdrawalDestinations","parameters":[{"description":"user_id represents the user identifier","in":"path","name":"userId","required":true,"schema":{"type":"string"}},{"description":"account_id represents the account identifier","in":"path","name":"accountId","required":true,"schema":{"type":"string"}},{"description":"name optionally filters destinations by name\nIt ignores case and matches any destination that contains the provided name","in":"query","name":"name","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1GetAccountWithdrawalDestinationsResponse"}}},"description":"A successful response."},"default":{"$ref":"#/components/responses/AppError"}},"summary":"GetAccountWithdrawalDestinations handle the request to get all withdrawal destinations for an account","tags":["AccountsQueryService"]}}}} ``` ## RegisterWithdrawalDestination handle the request to register a withdrawal destination > payload's shape depends on rail\_code/rail\_version — check\ > GetAllRailSchemas to know what fields to send. The destination isn't\ > usable until ConfirmWithdrawalDestination completes verification ```json {"openapi":"3.0.0","info":{"title":"KiiChain Pay Backend","version":"v1"},"tags":[{"description":"Commands (write operations)","name":"AccountsMsgService"}],"servers":[{"description":"Production","url":"https://backend.pay.kiichain.io"},{"description":"Staging","url":"https://backend.pay.staging.kiichain.io"}],"security":[{"ApiKeyAuth":["accounts.withdrawal_destination.write"]},{"BearerAuth":["accounts.withdrawal_destination.write"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Send 'Authorization: APIKey ' to authenticate with a API key.","in":"header","name":"Authorization","type":"apiKey"},"BearerAuth":{"flows":{"password":{"scopes":{},"tokenUrl":"https://backend.pay.kiichain.io/users/v1/auth/login"}},"type":"oauth2"}},"schemas":{"AccountsMsgServiceRegisterWithdrawalDestinationBody":{"properties":{"name":{"title":"name represents the name of the withdrawal destination","type":"string"},"payload":{"title":"Rail-specific payload (dynamic schema)","type":"object"},"railCode":{"title":"rail_code represents the rail code","type":"string"},"railVersion":{"format":"int32","title":"rail_version represents the rail version","type":"integer"}},"required":["railCode","railVersion","payload","name"],"title":"RegisterWithdrawalDestinationRequest is the body request structure from the RegisterWithdrawalDestination endpoint","type":"object"},"v1RegisterWithdrawalDestinationResponse":{"title":"RegisterWithdrawalDestinationResponse is the body response structure from the RegisterWithdrawalDestination endpoint","type":"object"},"AppErrorStatus":{"description":"The error envelope this API returns for every non-2xx response. `details` always contains exactly one AppError.","properties":{"code":{"description":"gRPC status code","format":"int32","type":"integer"},"details":{"description":"Always contains exactly one AppError","items":{"$ref":"#/components/schemas/AppError"},"type":"array"},"message":{"description":"Human-readable error message","type":"string"}},"type":"object"},"AppError":{"description":"Structured error detail responded by any non-2xx response.","properties":{"@type":{"description":"Protobuf Any type URL, always \"type.googleapis.com/pay.common.error.v1.AppError\" for this API","type":"string"},"internalCode":{"description":"Internal error code, unique within the module","format":"int32","type":"integer"},"message":{"description":"Human-readable error message","type":"string"},"meta":{"additionalProperties":{"type":"string"},"description":"Additional structured context for the error, if any","type":"object"},"module":{"description":"Module name where the error occurred (e.g. \"accounts\", \"market\")","type":"string"}},"type":"object"}},"responses":{"AppError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorStatus"}}},"description":"An unexpected error response. `details[0]` is always an AppError, see #/components/schemas/AppError"}}},"paths":{"/accounts/v1/users/{userId}/accounts/{accountId}/withdrawal_destinations":{"post":{"description":"payload's shape depends on rail_code/rail_version — check\nGetAllRailSchemas to know what fields to send. The destination isn't\nusable until ConfirmWithdrawalDestination completes verification","operationId":"AccountsMsgService_RegisterWithdrawalDestination","parameters":[{"description":"user_id represents the user identifier","in":"path","name":"userId","required":true,"schema":{"type":"string"}},{"description":"account_id represents the account identifier","in":"path","name":"accountId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountsMsgServiceRegisterWithdrawalDestinationBody"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1RegisterWithdrawalDestinationResponse"}}},"description":"A successful response."},"default":{"$ref":"#/components/responses/AppError"}},"summary":"RegisterWithdrawalDestination handle the request to register a withdrawal destination","tags":["AccountsMsgService"]}}}} ``` ## DeleteWithdrawalDestination handle the request to delete a withdrawal destination > Removes the destination whether it's pending or already confirmed ```json {"openapi":"3.0.0","info":{"title":"KiiChain Pay Backend","version":"v1"},"tags":[{"description":"Commands (write operations)","name":"AccountsMsgService"}],"servers":[{"description":"Production","url":"https://backend.pay.kiichain.io"},{"description":"Staging","url":"https://backend.pay.staging.kiichain.io"}],"security":[{"ApiKeyAuth":["accounts.withdrawal_destination.write"]},{"BearerAuth":["accounts.withdrawal_destination.write"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Send 'Authorization: APIKey ' to authenticate with a API key.","in":"header","name":"Authorization","type":"apiKey"},"BearerAuth":{"flows":{"password":{"scopes":{},"tokenUrl":"https://backend.pay.kiichain.io/users/v1/auth/login"}},"type":"oauth2"}},"schemas":{"v1DeleteWithdrawalDestinationResponse":{"title":"DeleteWithdrawalDestinationResponse is the body response structure from the DeleteWithdrawalDestination endpoint","type":"object"},"AppErrorStatus":{"description":"The error envelope this API returns for every non-2xx response. `details` always contains exactly one AppError.","properties":{"code":{"description":"gRPC status code","format":"int32","type":"integer"},"details":{"description":"Always contains exactly one AppError","items":{"$ref":"#/components/schemas/AppError"},"type":"array"},"message":{"description":"Human-readable error message","type":"string"}},"type":"object"},"AppError":{"description":"Structured error detail responded by any non-2xx response.","properties":{"@type":{"description":"Protobuf Any type URL, always \"type.googleapis.com/pay.common.error.v1.AppError\" for this API","type":"string"},"internalCode":{"description":"Internal error code, unique within the module","format":"int32","type":"integer"},"message":{"description":"Human-readable error message","type":"string"},"meta":{"additionalProperties":{"type":"string"},"description":"Additional structured context for the error, if any","type":"object"},"module":{"description":"Module name where the error occurred (e.g. \"accounts\", \"market\")","type":"string"}},"type":"object"}},"responses":{"AppError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorStatus"}}},"description":"An unexpected error response. `details[0]` is always an AppError, see #/components/schemas/AppError"}}},"paths":{"/accounts/v1/users/{userId}/accounts/{accountId}/withdrawal_destinations/{destinationId}":{"delete":{"description":"Removes the destination whether it's pending or already confirmed","operationId":"AccountsMsgService_DeleteWithdrawalDestination","parameters":[{"description":"user_id represents the user identifier","in":"path","name":"userId","required":true,"schema":{"type":"string"}},{"description":"account_id represents the account identifier","in":"path","name":"accountId","required":true,"schema":{"type":"string"}},{"description":"destination_id represents the withdrawal destination identifier","in":"path","name":"destinationId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1DeleteWithdrawalDestinationResponse"}}},"description":"A successful response."},"default":{"$ref":"#/components/responses/AppError"}},"summary":"DeleteWithdrawalDestination handle the request to delete a withdrawal destination","tags":["AccountsMsgService"]}}}} ``` ## UpdateWithdrawalDestination handle the request to update a withdrawal destination > Only renames the destination. The rail payload itself can't be changed,\ > register a new destination instead if those details need to change ```json {"openapi":"3.0.0","info":{"title":"KiiChain Pay Backend","version":"v1"},"tags":[{"description":"Commands (write operations)","name":"AccountsMsgService"}],"servers":[{"description":"Production","url":"https://backend.pay.kiichain.io"},{"description":"Staging","url":"https://backend.pay.staging.kiichain.io"}],"security":[{"ApiKeyAuth":["accounts.withdrawal_destination.write"]},{"BearerAuth":["accounts.withdrawal_destination.write"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Send 'Authorization: APIKey ' to authenticate with a API key.","in":"header","name":"Authorization","type":"apiKey"},"BearerAuth":{"flows":{"password":{"scopes":{},"tokenUrl":"https://backend.pay.kiichain.io/users/v1/auth/login"}},"type":"oauth2"}},"schemas":{"AccountsMsgServiceUpdateWithdrawalDestinationBody":{"properties":{"name":{"title":"name is the new label for this destination","type":"string"}},"required":["name"],"title":"UpdateWithdrawalDestinationRequest is the body request structure from the UpdateWithdrawalDestination endpoint","type":"object"},"v1UpdateWithdrawalDestinationResponse":{"title":"UpdateWithdrawalDestinationResponse is the body response structure from the UpdateWithdrawalDestination endpoint","type":"object"},"AppErrorStatus":{"description":"The error envelope this API returns for every non-2xx response. `details` always contains exactly one AppError.","properties":{"code":{"description":"gRPC status code","format":"int32","type":"integer"},"details":{"description":"Always contains exactly one AppError","items":{"$ref":"#/components/schemas/AppError"},"type":"array"},"message":{"description":"Human-readable error message","type":"string"}},"type":"object"},"AppError":{"description":"Structured error detail responded by any non-2xx response.","properties":{"@type":{"description":"Protobuf Any type URL, always \"type.googleapis.com/pay.common.error.v1.AppError\" for this API","type":"string"},"internalCode":{"description":"Internal error code, unique within the module","format":"int32","type":"integer"},"message":{"description":"Human-readable error message","type":"string"},"meta":{"additionalProperties":{"type":"string"},"description":"Additional structured context for the error, if any","type":"object"},"module":{"description":"Module name where the error occurred (e.g. \"accounts\", \"market\")","type":"string"}},"type":"object"}},"responses":{"AppError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorStatus"}}},"description":"An unexpected error response. `details[0]` is always an AppError, see #/components/schemas/AppError"}}},"paths":{"/accounts/v1/users/{userId}/accounts/{accountId}/withdrawal_destinations/{destinationId}":{"patch":{"description":"Only renames the destination. The rail payload itself can't be changed,\nregister a new destination instead if those details need to change","operationId":"AccountsMsgService_UpdateWithdrawalDestination","parameters":[{"description":"user_id represents the user identifier","in":"path","name":"userId","required":true,"schema":{"type":"string"}},{"description":"account_id represents the account identifier","in":"path","name":"accountId","required":true,"schema":{"type":"string"}},{"description":"destination_id represents the withdrawal destination identifier","in":"path","name":"destinationId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountsMsgServiceUpdateWithdrawalDestinationBody"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1UpdateWithdrawalDestinationResponse"}}},"description":"A successful response."},"default":{"$ref":"#/components/responses/AppError"}},"summary":"UpdateWithdrawalDestination handle the request to update a withdrawal destination","tags":["AccountsMsgService"]}}}} ``` ## ConfirmWithdrawalDestination handle the request to confirm a withdrawal destination > verify\_code is the one-time code sent out after RegisterWithdrawalDestination\ > — moves the destination from pending to confirmed ```json {"openapi":"3.0.0","info":{"title":"KiiChain Pay Backend","version":"v1"},"tags":[{"description":"Commands (write operations)","name":"AccountsMsgService"}],"servers":[{"description":"Production","url":"https://backend.pay.kiichain.io"},{"description":"Staging","url":"https://backend.pay.staging.kiichain.io"}],"security":[{"ApiKeyAuth":["accounts.withdrawal_destination.write"]},{"BearerAuth":["accounts.withdrawal_destination.write"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Send 'Authorization: APIKey ' to authenticate with a API key.","in":"header","name":"Authorization","type":"apiKey"},"BearerAuth":{"flows":{"password":{"scopes":{},"tokenUrl":"https://backend.pay.kiichain.io/users/v1/auth/login"}},"type":"oauth2"}},"schemas":{"v1AccountsMsgServiceConfirmWithdrawalDestinationBody":{"properties":{"verifyCode":{"title":"verify_code represents the one time code to verify the destination created","type":"string"}},"required":["verifyCode"],"title":"ConfirmWithdrawalDestinationRequest is the body request structure from the ConfirmWithdrawalDestination endpoint","type":"object"},"v1ConfirmWithdrawalDestinationResponse":{"title":"ConfirmWithdrawalDestinationResponse is the body response structure from the ConfirmWithdrawalDestination endpoint","type":"object"},"AppErrorStatus":{"description":"The error envelope this API returns for every non-2xx response. `details` always contains exactly one AppError.","properties":{"code":{"description":"gRPC status code","format":"int32","type":"integer"},"details":{"description":"Always contains exactly one AppError","items":{"$ref":"#/components/schemas/AppError"},"type":"array"},"message":{"description":"Human-readable error message","type":"string"}},"type":"object"},"AppError":{"description":"Structured error detail responded by any non-2xx response.","properties":{"@type":{"description":"Protobuf Any type URL, always \"type.googleapis.com/pay.common.error.v1.AppError\" for this API","type":"string"},"internalCode":{"description":"Internal error code, unique within the module","format":"int32","type":"integer"},"message":{"description":"Human-readable error message","type":"string"},"meta":{"additionalProperties":{"type":"string"},"description":"Additional structured context for the error, if any","type":"object"},"module":{"description":"Module name where the error occurred (e.g. \"accounts\", \"market\")","type":"string"}},"type":"object"}},"responses":{"AppError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorStatus"}}},"description":"An unexpected error response. `details[0]` is always an AppError, see #/components/schemas/AppError"}}},"paths":{"/accounts/v1/users/{userId}/accounts/{accountId}/withdrawal_destinations/{destinationId}:confirm":{"post":{"description":"verify_code is the one-time code sent out after RegisterWithdrawalDestination\n— moves the destination from pending to confirmed","operationId":"AccountsMsgService_ConfirmWithdrawalDestination","parameters":[{"description":"user_id represents the user identifier","in":"path","name":"userId","required":true,"schema":{"type":"string"}},{"description":"account_id represents the account identifier","in":"path","name":"accountId","required":true,"schema":{"type":"string"}},{"description":"destination_id represents the withdrawal destination identifier","in":"path","name":"destinationId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1AccountsMsgServiceConfirmWithdrawalDestinationBody"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ConfirmWithdrawalDestinationResponse"}}},"description":"A successful response."},"default":{"$ref":"#/components/responses/AppError"}},"summary":"ConfirmWithdrawalDestination handle the request to confirm a withdrawal destination","tags":["AccountsMsgService"]}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.kiiglobal.io/docs/kiichain-pay/api-reference/accounts.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.