Complete GraphQL API documentation for institutional digital asset infrastructure. Access real-time data, execute transactions, and integrate seamlessly with our platform.
Comprehensive GraphQL/PostGraphile API with complete sections for all institutional digital asset operations
Seven core sections plus appendix covering all aspects of institutional digital asset infrastructure
The Vertalo platform is a modern, blockchain-aware architecture that supports many functions, including:
As an "integration first" company, Vertalo has designed its platform in an open and flexible way. This makes it possible for our partners to integrate with our platform through the Vertalo API when and where it's needed. This could range from pushing or pulling data for a specific purpose to a full scale implementation of a custom UI that you design. (The Vertalo portal is, in fact, a reference application built on top of our own API.)
The key to understanding how our API operates is understanding the GraphQL specification originally conceived of by Facebook in 2012. GraphQL is now an open standard that any vendor can implement. It is very different from the traditional REST model and the overhead that is frequently associated with having to make multiple round trips to various endpoints in order to perform the actions you want, and the frequent over/under fetching that ensues. Instead, a GraphQL implementation exposes a single endpoint that can accept complex queries and mutations based on a uniform query language. It is then up to the server-side GraphQL implementation to resolve the request, reading or writing data as directed across one or more data sources.
Vertalo has established a GraphQL schema that allows our integration partners to read/write information from/to the Vertalo platform.
This primer is by no means exhaustive, but is meant to get you well-grounded in the basics of the Vertalo API so that you can explore further on your own. The ordering of sections throughout this primer represents the typical order of operations you will perform using the API relative to your account/role. If you require further support in your exploration of the Vertalo API, please contact Vertalo at integrations@vertalo.com.
It's important that you understand the basic Vertalo access control model and how your API access fits within it. A central part of the Vertalo access control model is the concept of roles. The following roles are currently supported:
Role Descriptions and System Privileges:
Every account on the platform is assigned one of these roles.
There is a distinction between accounts and users in the Vertalo system. An account defines an entity in the system to which a single role is assigned (for instance, the issuer role). One or more users are then assigned as a delegate to the account and these users exercise the rights that the role allows. So in effect, an account is a collection of privileges granted to an entity.
Delegation
The delegation model described above allows for a one-to-many relationship between account and users, and gives you a great deal of flexibility as to how to manage access to the accounts you control. For any account created on the platform, a default delegate (user) will be automatically defined; the delegate will vary depending on the context in which the account was created (for instance, via the Vertalo portal vs. API-based creation).
As a multi-tenant system, an investor has a single account in the Vertalo platform regardless of how many different vendors with which they may be engaged. For instance, an investor may hold shares with both Issuer A and Issuer B. From an investor perspective, the investor is a customer to each issuer but has only one account in the system. The challenge comes when allowing each vendor to maintain its own version of the investor's details (name, address, etc.).
Customer Records
To support vendor-specific investor details, the platform allows each vendor to create unique customer records (including personal information) for investors with which they are engaging, establishing a unique connection between vendor and investor without the possibility of overlap with other vendors. This operation is detailed in the section Issuer Actions/Investor Setup.
Your starting point for exploring the Vertalo API is the Vertalo Sandbox. The Sandbox is a fully functioning version of our production environment and allows participants to model assets, rounds and other entities to investors in a safe and controlled manner. For an organization that is interested in leveraging the Vertalo API, the Sandbox also offers a way to explore and try out the API through an interactive interface. Follow these steps to access this environment:
You will be presented with an interactive GraphQL explorer called GraphiQL. Using GraphiQL, you can compose and execute GraphQL queries and mutations. Most importantly, you have access to a documentation panel on the right side of the screen that exposes the entire GraphQL schema and Vertalo API.
To execute a query or mutation you've composed in the left pane, click the "play" button just above the left pane.
IMPORTANT: The actions available to you in the API are entirely role-sensitive. For instance, the actions available to you in a "broker role" will be very different that those available to you in an "issuer role". Role selection is possible through both the Vertalo user portal and during the authentication/authorization process with API keys.
IMPORTANT: There may be instances where, for a particular object, you see dual mutations in the API in the form of "make<Object>" and "create<Object>". In these instances, use the "make<Object>" form. For example, use "makeRound" rather than "createRound".
The Vertalo object model consists of the following major components:
As you peruse the API documentation in GraphiQL, you'll see these objects appearing in root-level fieldnames, type names, and other areas of the API. The examples in this section represent a good starting point for your exploration of the Vertalo API.
The basic pre-issuance object hierarchy is:
The basic post-issuance object hierarchy is:
Understanding the parent/child relationships expressed above is essential. And while you may create this hierarchy either manually using the Vertalo portal or programmatically using the API, you must ensure that parent objects exist before attempting to create related child objects.
Exploring the Object Hierarchy
In this example, the query traverses the Vertalo object hierarchy in order to expose detail at multiple levels. It is critical that you understand how objects relate to one another in order to drill down to the information you want to access or create. Also, you should notice how the shape of the resulting data matches the shape of the query in the above example. This is a feature of GraphQL. In the case of this example, the object hierarchy is expressed both in the query and the result.
Query Assets
In this example, the query returns a list of assets. Notice that the shape of the result (expressed as JSON) matches the shape of the query. This is an important feature of GraphQL.
Query Accounts
In this example, the query returns a list of accounts including the fields you requested (collectively known as the query's payload). Notice the use of arguments ("last") to refine the results of the query. In this case, only the first 3 accounts are returned. The type definition of a root field (as shown in the Documentation Explorer) will describe any arguments that the field supports.
As a digital transfer agent, Vertalo sits at the intersection of a digital asset ecosystem that includes key partners providing the following services:
The Vertalo platform is integrated with partners in each of these categories. These integrations, however, are not available to issuers or brokers through the API as they require investor login. The platform enforces safeguards that prevent an issuer or broker from acting on behalf of an investor for certain actions and thereby ensuring investor protection.
The Vertalo GraphQL API is derived from a collection of PostgreSQL databases that underpin our platform. We also use an open-source framework called PostGraphile, which is able to interpret a PostgreSQL schema and then auto-generate a GraphQL schema from it. It is recommended that you gain some familiarity with PostGraphile in order to understand how the Vertalo API is created. The PostGraphile documentation provides a roadmap to what you'll see in the Vertalo API. In particular, the following concepts are important to your understanding of how to interact with our API:
This nomenclature is borrowed from discrete mathematics and applies to graphs. This makes sense when you consider that Facebook (the creator of GraphQL) is a social graph company and, therefore, thinks of data in terms of graphs; specifically, how different entities relate to one another and the connections between them. GraphQL is an expression of this approach, but can actually be applied to any dataset.
A purely internal, proprietary blockchain underpins the Vertalo software model, creating a complex web of relationships between pre-issuance and post-issuance events/objects. As a purpose-built digital asset ledger, this architecture also allows for a consistent, clean mapping between internal events (typically related to the issuance and transfer of shares) and those on the external blockchains with which Vertalo is integrated. As you explore and traverse the Vertalo GraphQL schema exposed through the API, you will see refererences to internal blockchain addresses throughout, and in many use cases these addresses allow you to make connections between various nodes in the graph.
This internal blockchain is integral to the Vertalo architecture regardless of whether you are leveraging an external blockchain (for tokenization, etc.) or not.
The actions for an issuer in a primary issuance context follow a typical ordering:
The sections of this chapter are laid out to follow this sequence.
Syndication
An issuer may choose to syndicate the fulfillment of a round by inviting brokers to participate. In this circumstance, the broker is effectively a quasi-issuer for that round and can perform certain similar functions to that of an issuer, specifically, creating allocations and distributions. Please refer to the appropriate sections under Issuer Actions for API details.
The Vertalo platform offers support for organizations that assist issuers with their digital securities offerings, including:
This type of organization is generically referred to as a "broker" in the Vertalo system, and there are specific capabilities associated with this role. If you fall within the broker category you may use the API to make use of these capabilities. Please refer to the Roles section of the Introduction for additional detail on broker privileges.
Syndication
An issuer may choose to syndicate the fulfillment of a round by inviting brokers to participate. In this circumstance, the broker is effectively a quasi-issuer for that round and can perform certain similar functions to that of an issuer, specifically, creating allocations and distributions.
IMPORTANT: Brokers may not issue shares or tokenize investor holdings; this is a privilege reserved for issuers only.
Please refer to the appropriate sections under Issuer Actions for API details.
ATS/Exchange integrations are standardized through an API derived from the Vertalo GraphQL schema. Because of the high compliance requirements/costs associated with post-issuance trading and transfer, the goal of the Vertalo API is designed to make it as easy as possible to convey data between systems in order to maximize consistency. While the Vertalo platform uses a transaction-based architecture under the hood, we do not currently expose this to the API user and translate trading and transfer calls to transactions as needed. (Future releases may expose low-level transaction calls.)
API calls are ordered, and will be preserved and executed in the order in which they are received. The platform will take instructions typically without regard to the state in which the system may be left. For example, a transfer could result in a securities balance for an investor going below zero. Because of the asynchronous nature of transactions, this state will be allowed (though a warning will be issued).
Custodian actions may be utilized by different parties depending on the requirements of their integration with the Vertalo platform. For instance, registered/qualified custodians may need to interact with an issuer's cap tables in order to request the transfer of holdings from an investor into an omnibus account in the name of the custodian. The same applies for registered/qualified BD/ATS's where the BD/ATS is permitted to hold an investor's securities in street-name for the purpose of trading.
All of the concepts, capabilities, and examples described previously in the API primer are available programmatically via API credentials. Vertalo will issue clients testing and production credentials (a client ID and client secret) for server-side programmatic access to their account(s). The process of using the credentials to claim the required access tokens and issue queries and mutations to the Vertalo API is described in the sections that follow. We strongly encourage you to use your regular login credentials to make use of Vertalo's user portal and interactive GraphiQL interface (described in detail above in this document), in addition to your testing API credentials, to test your queries in your sandbox environment before implementing them in production. Tokens you receive from the Vertalo API endpoints have an expiration time of 60 minutes, after which you will receive HTTP 401 errors. You will need to manage your use of tokens to account for expiration and request new tokens as needed.
IMPORTANT: Please be sure to guard your Vertalo-provided credentials carefully in order to prevent inadvertent or malicious activity that could negatively affect your account(s).
IMPORTANT: Your ability to leverage the different capabilities exposed through the Vertalo API will vary depending on the rights granted to your API credentials. Not all services and actions will be available.
These coding examples are meant to provide you with guidance on how to program the process of authenticating and authorizing with the Vertalo platform via the API, and show examples of how to submit queries to the Vertalo GraphQL endpoint. You will need to request your API credentials from Vertalo before you can access the API.