Documentation to Compoundfolio GraphQL API

"""
Asset group is a "Folder" that may contain assets of certain types and other groups.
Asset groups appear on the burst chart.
"""
type AssetGroup {
	"""
	Id that is unique for this asset group.
	"""
	id: UUID!
	"""
	This is how the asset group should appear for the user.
	"""
	name: String!
	"""
	Describes which portion of the portfolio (or parent group) this group
	must occupy, comparing by total value of assets stored in it.
	Is updated by user, and not calculated dynamically.
	"""
	targetAllocationPercentage: Decimal
	"""
	Contains all asset groups and assets that reference this asset group
	as a parent. In order for this array to be updated, update parent id
	of underlying children.
	"""
	children: [AssetGroupChild!]!
}

"""
Asset group child is a union type that includes other assets groups
or assets themselves.
"""
union AssetGroupChild = AssetGroup | AssetSlot

type AssetInPortofioWithStats {
	listing: Listing!
	shares: Float!
	currentPrice: Float!
	totalWorth: Float!
	yieldPercentage: Float!
	yieldOnCost: Float!
	dividendGrowth10Y: Float!
	totalReturnPercentage: Float!
	totalReturnDollars: Float!
	portfolioPercentage: Float!
}

"""
Asset slot is a space in your portfolio structure, reserved for a specific traded asset.
Asset slots appear on the burst chart.
"""
type AssetSlot {
	"""
	Id that is unique for this asset slot.
	"""
	id: UUID!
	"""
	Describes which portion of the portfolio (or parent asset group) this slot
	must occupy, comparing by total value of assets stored in it.
	Is updated by user, and not calculated dynamically.
	"""
	targetAllocationPercentage: Decimal
	"""
	Asset that this slot is reserved for.
	"""
	asset: SimpleStandaloneAsset!
}

enum BrokerType {
	EXANTE
	FREEDOMFINANCE
	INTERACTIVEBROKERS
}

type BrokerageUserTransactionTypeCount {
	"""
	When null - represents transactions without brokerage specified
	"""
	brokerage: BrokerType
	"""
	Contains aggereggated count of user transactions types
	of transactions that were assigned to this brokerage
	"""
	perTypeCount: [UserTransactionTypeCount!]!
}

type Charts {
	sunburst: [SunburstChartLeaf!]!
	netWorth: SimpleHistoricLineChart!
}

input CreateFiscalTransactionRequest {
	"""
	Transaction must be associated with a portfolio. Transaction can
	be moved by updating its portfolio id.
	"""
	portfolioId: UUID!
	"""
	Associate this transaction with a broker.
	"""
	brokerage: BrokerType
	"""
	Date and time at which this transaction occurred in a local timezone
	"""
	dateTime: NaiveDateTime!
	"""
	Associate this transaction with an instrument. Field value is validated.
	Must be present for DIVIDEND. Must be null for FUNDIG_WITHDRAWAL.
	"""
	ticker: String
	"""
	Total transaction amount, must always be positive.
	"""
	amount: MoneyInput!
	transactionType: CreateableFiscalTransactionType!
}

input CreatePortfolio {
	title: String!
}

input CreateTradeOperationRequest {
	"""
	Trade must be associated with a portfolio. Trade can
	be moved by updating its portfolio id.
	"""
	portfolioId: UUID!
	"""
	Ticker of the traded security, instrument symbol.
	"""
	ticker: String!
	"""
	Buy or sell.
	"""
	side: TradeOperationSide!
	"""
	Price of a single security in this transaction. Must be positive.
	"""
	price: MoneyInput!
	"""
	Quantity of traded securities. Must be positive.
	"""
	quantity: Decimal!
	"""
	Required total amount of currency paid for the trade. Must be positive.
	"""
	summ: MoneyInput!
	"""
	Optionally provide an ISIN identificator.
	"""
	isin: String
	"""
	Date and time at which this transaction occurred in a local timezone.
	"""
	dateTime: NaiveDateTime!
	"""
	Associate this transaction with a broker. Not required.
	"""
	brokerage: BrokerType
	"""
	Trading commission, paid to brokerage for their services for each transaction.
	"""
	commission: MoneyInput
	"""
	Optionally provide known internal asset listing id.
	"""
	assetListingId: UUID
}

enum CreateableFiscalTransactionType {
	TAX
	DIVIDEND_TAX
	DIVIDEND
	FUNDING
	WITHDRAWAL
	COMMISSION
}

scalar Decimal

input GenericPageRequest {
	from: Int!
	to: Int!
}

type HistoricLineChartDataPoint {
	x: NaiveDate!
	y: Float!
}

type Listing {
	"""
	Internal asset listing id. One asset has a separate listing on each exchange.
	"""
	id: UUID!
	"""
	This listing is for the following asset.
	"""
	asset: SimpleStandaloneAsset!
	"""
	Ticket without exchange code, for example "SCHD"
	"""
	ticker: String!
	"""
	Exchange code that you can append to the ticker, like "ARCA"
	"""
	exchange: String!
	"""
	Code of currency this asset is traded in
	"""
	currency: String!
	"""
	Known ISIN of this listing, optional
	"""
	isin: String
}

"""
When you manage an asset group as a whole, you provide children in a single array.
GraphQL does not (yet) support Union input types, the solution is to provide
subtypes by storing them in separate fields. You can only provide ONE field.
This type allows you to input either a child asset group, or an asset slot.
"""
input ManageAssetGroupChild @oneOf {
	assetGroup: ManageAssetGroupChildGroup
	assetSlot: ManageAssetGroupChildSlot
}

input ManageAssetGroupChildGroup {
	"""
	Provide ID to indicate this asset group already exists.
	Leave empty to create a new asset group.
	"""
	id: UUID
	"""
	Asset group display name. Needs to be provided every time.
	"""
	name: String!
	"""
	If supplied, the value must be between 0 and 100.
	It is stored with a precision of 2 decimal points.
	"""
	targetAllocationPercentage: Float
}

input ManageAssetGroupChildSlot {
	"""
	Provide ID to indicate this asset slot already exists.
	If empty, this creates a new asset slot.
	Asset slots require their own ID, separate from classic "asset" ids,
	because we support adding the same asset into multiple asset groups.
	"""
	id: UUID
	"""
	Internal (our) ID of an asset that will be assigned to this slot.
	"""
	assetId: UUID!
	"""
	If supplied, the value must be between 0 and 100.
	It is stored with a precision of 2 decimal points.
	"""
	targetAllocationPercentage: Float
}

"""
Contains information about the updates that should be made to the asset groups.
"""
input ManageAssetGroupsRequest {
	"""
	ID of the updated asset group. Leave empty to update the top level of the portfolio.
	"""
	id: UUID
	"""
	You may update the name of the asset group if you include this field.
	Does nothing when ID is NULL.
	"""
	name: String
	"""
	Complete list of children for the updated asset group. Contains "asset slots"
	and other assset groups. Will be saved in the order you provided.
	Warning! If you don't provide existing children, they will be erased!
	"""
	children: [ManageAssetGroupChild!]!
}

type Me {
	email: String!
}

type Money {
	amount: Decimal!
	currency: String!
}

input MoneyInput {
	amount: Decimal!
	currency: String!
}

type MutationRoot {
	"""
	Create a new portfolio
	"""
	createPortfolio(data: CreatePortfolio!): Portfolio!
	"""
	Create a new portfolio
	"""
	updatePortfolio(data: UpdatePortfolio!): Portfolio!
	"""
	Delete portfolio
	"""
	deletePortfolio(id: UUID!): String!
	"""
	Accepts uploads with size up to 10 MB.
	"""
	uploadReport(portfolioId: UUID!, brokerage: BrokerType!, upload: Upload!): ReportUploadResult!
	"""
	Create a new fiscal transaction within a portfolio identified by id.
	Create request is validated.
	Returns ID of created fiscal transaction.
	"""
	createFiscalTransaction(createRequest: CreateFiscalTransactionRequest!): UUID!
	"""
	Update existing fiscal transaction, identified by ID.
	Update request is validated.
	"""
	updateFiscalTransaction(updateRequest: UpdateFiscalTransactionRequest!): String!
	"""
	Create a new trade opration within a portfolio identified by id
	"""
	createTradeOperation(createRequest: CreateTradeOperationRequest!): UUID!
	"""
	Update existing trade, identified by ID.
	Update request is validated.
	"""
	updateTradeOperation(updateRequest: UpdateTradeOperationRequest!): String!
	"""
	Delete one or multiple user transaction, regardless of their type.
	Transactions that don't belong to user won't be deleted.
	"""
	deleteUserTransactions(ids: [UUID!]!): String!
	"""
	Delete all user transactions that belong to a portfolio.
	"""
	deleteUserTransactionsByPortfolio(portfolioId: UUID!): String!
	"""
	Delete all user transactions of a specific broker in a portfolio.
	If `brokerage` is not provided, only transactions without brokerage are deleted.
	"""
	deleteUserTransactionsByPortfolioAndBrokerage(portfolioId: UUID!, brokerage: BrokerType): String!
	"""
	Smart method to manage asset groups in one query.
	"""
	manageAssetGroups(portfolioId: UUID!, data: ManageAssetGroupsRequest!): String!
}

"""
ISO 8601 calendar date without timezone.
Format: %Y-%m-%d

# Examples

* `1994-11-13`
* `2000-02-24`
"""
scalar NaiveDate

"""
ISO 8601 combined date and time without timezone.

# Examples

* `2015-07-01T08:59:60.123`,
"""
scalar NaiveDateTime

type Portfolio {
	id: UUID!
	title: String!
	brokerages: [BrokerType!]!
	amountOfUserTransactions: Int!
	"""
	List all the "brokerage report" files that were imported into that portfolio
	"""
	reportUploads: [ReportUploadResult!]!
	assets: PortfolioAssets!
	totalReturnPercentage: Decimal!
	totalReturnValue: Money!
	annualIncome: Money!
	"""
	Get all transactions of the portfolio, regardless of their type.
	Supports pagination and filtering by history markers
	"""
	userTransactions(pageRequest: GenericPageRequest!, filteringOptions: UserTransactionsFilteringOptions): UserTransactionPage!
	"""
	Get count for each type of user transaction, grouped by brokerages.
	"""
	userTransactionsStatistics: [BrokerageUserTransactionTypeCount!]!
	"""
	Get count of user transactions, aggregated by their filtering options.
	"""
	userTransactionsFilteredCounts: UserTransactionsFilteredCounts!
	"""
	Object that contains functions to generate chart data for a specific portfolio.
	"""
	charts: Charts!
	"""
	Contains tree structure of this portfolios assets, organized by groups that
	store these assets and other groups.
	"""
	groups: [AssetGroupChild!]!
	"""
	List of assets that are in the portfolio, but not included into any group, i.e. there
	are no asset slots for them. Empty search string allows to display all ungruped assets.
	"""
	ungroupedAssets(searchString: String!): [Listing!]!
}

type PortfolioAssets {
	"""
	Get a list of all assets in the portfolio with detailed information
	"""
	portfolioAssets: [AssetInPortofioWithStats!]!
}

type QueryRoot {
	"""
	Information about you as a signed in user
	"""
	me: Me!
	"""
	List of portfolios that belong to you.
	"""
	portfolios: [Portfolio!]!
	"""
	Find portfolio by its id.
	"""
	portfolioById(id: UUID!): Portfolio!
	"""
	Search through all possible traded assets using a fuzzy search string input by user.
	Assets will have a listing attached. If user was searching by the ticker, the listing
	will be of a corresponding ticker. Otherwise, default ticker will be attached.
	Listings are ordered by how close they are to the match string.
	"""
	assetSearch(searchString: String!): [Listing!]!
}

type ReportUploadResult {
	id: UUID!
	filename: String!
	createdAt: NaiveDateTime!
	brokerage: BrokerType!
}

"""
Contains data for plotting a line x-y chart with only one metric,
where each value is assigned to a date.
"""
type SimpleHistoricLineChart {
	metric: [HistoricLineChartDataPoint!]!
	unit: String!
}

type SimpleStandaloneAsset {
	"""
	Internal asset ID.
	"""
	id: UUID!
	"""
	Asset name, for example company name for a share.
	"""
	name: String!
	"""
	Most widely known ticker of this asset.
	"""
	ticker: String!
}

type SunburstChartAsset {
	"""
	Id of the asset slot that this asset takes, that user configured earlier.
	Will be empty if this is an ungrouped asset.
	"""
	assetSlotId: UUID
	"""
	Contains information about the asset itself.
	"""
	asset: SimpleStandaloneAsset!
	"""
	User's configured "target" portion for this asset to take.
	Will be empty if user has not configured this, or if `asset_slot_id` is empty.
	"""
	targetAllocationPercentage: Decimal
	"""
	Portion of the parent node that this asset takes.
	"""
	realAllocationPercentage: Decimal!
	"""
	Portion of the entire portfolio that this asset takes
	"""
	realPortfolioPercentage: Decimal!
	"""
	Value/worth of this asset in the portfolio's display currency.
	"""
	referenceValue: Money!
}

type SunburstChartGroup {
	"""
	Id of the asset slot that this asset occupies, that user configured earlier.
	"""
	assetGroupId: UUID!
	"""
	How user has tagged/labeled this asset group.
	"""
	assetGroupName: String!
	"""
	User's configured "target" portion for this asset to take
	"""
	targetAllocationPercentage: Decimal
	"""
	Portion of the parent node that this asset takes.
	"""
	realAllocationPercentage: Decimal!
	"""
	Portion of the entire portfolio that this asset takes
	"""
	realPortfolioPercentage: Decimal!
	"""
	Children asset slots and asset groups.
	"""
	children: [SunburstChartLeaf!]!
	"""
	Value/worth of this asset in the portfolio's display currency.
	"""
	referenceValue: Money!
}

union SunburstChartLeaf = SunburstChartGroup | SunburstChartAsset

enum TradeOperationSide {
	BUY
	SELL
}

"""
A UUID is a unique 128-bit number, stored as 16 octets. UUIDs are parsed as
Strings within GraphQL. UUIDs are used to assign unique identifiers to
entities without requiring a central allocating authority.

# References

* [Wikipedia: Universally Unique Identifier](http://en.wikipedia.org/wiki/Universally_unique_identifier)
* [RFC4122: A Universally Unique Identifier (UUID) URN Namespace](http://tools.ietf.org/html/rfc4122)
"""
scalar UUID

input UpdateFiscalTransactionRequest {
	"""
	ID of fiscal transaction you want ot update.
	"""
	id: UUID!
	"""
	Transaction must be associated with a portfolio. Transaction can
	be moved by updating its portfolio id.
	"""
	portfolioId: UUID!
	"""
	Associate this transaction with a broker.
	"""
	brokerage: BrokerType
	"""
	Date and time at which this transaction occurred in a local timezone
	"""
	dateTime: NaiveDateTime!
	"""
	Associate this transaction with an instrument. Field value is validated.
	Must be present for DIVIDEND. Must be null for FUNDIG_WITHDRAWAL.
	"""
	ticker: String
	"""
	Total transaction amount, must always be positive.
	"""
	amount: MoneyInput!
	transactionType: CreateableFiscalTransactionType!
}

input UpdatePortfolio {
	id: UUID!
	title: String!
}

input UpdateTradeOperationRequest {
	"""
	ID of fiscal transaction you want ot update.
	"""
	id: UUID!
	"""
	Trade must be associated with a portfolio. Trade can
	be moved by updating its portfolio id.
	"""
	portfolioId: UUID!
	"""
	Ticker of the traded security, instrument symbol.
	"""
	ticker: String!
	"""
	Buy or sell.
	"""
	side: TradeOperationSide!
	"""
	Price of a single security in this transaction. Must be positive.
	"""
	price: MoneyInput!
	"""
	Quantity of traded securities. Must be positive.
	"""
	quantity: Decimal!
	"""
	Required total amount of currency paid for the trade. Must be positive.
	"""
	summ: MoneyInput!
	"""
	Optionally provide an ISIN identificator.
	"""
	isin: String
	"""
	Date and time at which this transaction occurred in a local timezone.
	"""
	dateTime: NaiveDateTime!
	"""
	Associate this transaction with a broker. Not required.
	"""
	brokerage: BrokerType
	"""
	Trading commission, paid to brokerage for their services for each transaction.
	"""
	commission: MoneyInput
	"""
	Optionally provide known internal asset listing id.
	"""
	assetListingId: UUID
}

scalar Upload

"""
User-transaction is any operation recorded in a portfolio, like trade
or a fiscal transaction, seen from user perspective as a single entity
type. In other words, it is an abstraction above trade operations and
fiscal transactions.
"""
type UserTransaction {
	"""
	Id that is unique for all kinds of transactions
	"""
	id: UUID!
	"""
	Indicates entity that this user transaction was derived from
	"""
	userTransactionClass: UserTransactionClass!
	"""
	Indicates original type of the transaction this user transaction was derived from.
	"""
	userTransactionType: UserTransactionType!
	"""
	Flag that indicates that this transaction increased amount of cash in user's account.
	"""
	isPositivePortfolioValueChange: Boolean!
	"""
	Optionally contains name of the brokerage that manages the transaction.
	"""
	brokerage: BrokerType
	"""
	total change of balance as a result of the transaction. Can be negative.
	"""
	summ: Money!
	"""
	Ticker of the related instrument. Appears in TRADE, DIVIDEND and sometimes TAX operations.
	"""
	ticker: String
	"""
	Appears in TRADE. Contains always positive price of a single instrument.
	"""
	price: Money
	"""
	Appears in TRADE. Contains always positive amount of securities in a trade.
	"""
	quantity: Decimal
	"""
	Appears in TRADE.
	"""
	tradeSide: UserTransactionTradeSide
	"""
	when user_transaction_type == UNRECOGINZED, contains the original transaction type.
	"""
	unrecognizedType: String
	"""
	Timestamp of an instant when the transaction occurred.
	"""
	dateTime: NaiveDateTime!
	"""
	Display name of stock exchange.
	"""
	stockExchange: String
	"""
	Country code of stock exchange (ISO_3166-1_alpha-2)
	"""
	exchangeCountryCode: String
	"""
	Display name of the traded instrument
	"""
	assetName: String
	"""
	Can be used to mark transactions by color, depending on how they are created and updated.
	"""
	transactionHistoryMarker: UserTransactionHistoryMarker!
	"""
	Appears in TRADE. Contains a positive amount of money withdrawn by a brokerage.
	"""
	commission: Money
}

"""
Since "user transaction" is an abstraction, this enum indicates concrete
class of the user transaction
"""
enum UserTransactionClass {
	TRADE_OPERATION
	FISCAL_TRANSACTION
}

"""
Indicates origin and history of a user transaction
"""
enum UserTransactionHistoryMarker {
	CREATED_MANUALLY
	CREATED_MANUALLY_AND_UPDATED_MANUALLY
	CREATED_FROM_REPORT
	CREATED_FROM_REPORT_AND_UPDATED_MANUALLY
}

type UserTransactionPage {
	records: [UserTransaction!]!
	totalRecords: Int!
	hasNextPage: Boolean!
	hasPreviousPage: Boolean!
}

enum UserTransactionTradeSide {
	BUY
	SELL
}

"""
Depending on this type, some of the fields in the UserTransaction can
be present or absent. WARNING: Might contain undocumented values.
"""
enum UserTransactionType {
	TRADE
	TAX
	DIVIDEND_TAX
	COMMISSION
	FUNDING
	WITHDRAWAL
	DIVIDEND
	"""
	Gets created when user report has DIVIDEND transaction with negative amount
	"""
	REVERTED_DIVIDEND
	"""
	Gets created when user report has TAX transaction with positive amount
	"""
	REVERTED_TAX
	"""
	An unknown type of transaction was recieved from a brokerage report.
	"""
	UNRECOGNIZED
}

type UserTransactionTypeCount {
	userTransactionType: UserTransactionType!
	tradeSide: UserTransactionTradeSide
	count: Int!
}

"""
Contains *estimated* totals of filtered user transactions. Keep in mind this should only be
used for display purposes, in order to query and paginate over user transactions themselves
use user transactions filtering options.
"""
type UserTransactionsFilteredCounts {
	"""
	Amount of user transactions that were edited through the user interface.
	"""
	updatedManuallyCount: Int!
	"""
	Amount of user transactions that were uploaded with a brokerage report.
	"""
	createdFromReportCount: Int!
	"""
	Amount of user transactions that were created through the user interface, i.e. not from report.
	"""
	createdManuallyCount: Int!
}

input UserTransactionsFilteringOptions {
	updatedManually: Boolean
	createdFromReport: Boolean
}

"""
Directs the executor to include this field or fragment only when the `if` argument is true.
"""
directive @include(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT
"""
Indicates that an Input Object is a OneOf Input Object (and thus requires exactly one of its field be provided)
"""
directive @oneOf on INPUT_OBJECT
"""
Directs the executor to skip this field or fragment when the `if` argument is true.
"""
directive @skip(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT
"""
Provides a scalar specification URL for specifying the behavior of custom scalar types.
"""
directive @specifiedBy(url: String!) on SCALAR
schema {
	query: QueryRoot
	mutation: MutationRoot
}