https://api.vertalo.com/ Recent content on Vertalo API Primer Hugo -- gohugo.io en Copyright © {year} Vertalo Inc., a SeriesX Company. All rights reserved. Sun, 26 Jan 2020 04:15:05 +0900 https://api.vertalo.com/docs/issuer/primary-issuance/create-distribution/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/issuer/primary-issuance/create-distribution/ Request: mutation { makeDistribution ( input: { _allocationId: "abb668d2-63d2-43dd-b495-b1e413a69427" accountEmail: "bob.smith@example.com" name: "Bob Smith" amount: "100000" } ) { distribution { id status } } } Response: { "data": { "makeDistribution": { "distribution": { "id": "8f444de2-bfd9-4ca5-b6f4-74c4e511cebc", "status": "drafted" } } } } A distribution is an initial assignment of a quantity of units (typically shares) to an investor within an allocation which is meant to represent a pro forma position that the investor is interested in taking in a particular offering. https://api.vertalo.com/docs/issuer/document-upload/security-document/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/issuer/document-upload/security-document/ Request: mutation { makeSecurityDocument( input: { name: "PPM", extension: "pdf", securityId: "5f30ff94-8bb7-490e-be24-8b935d786b93", shareWith: [] }) { uploadInfo securityDocumentId accountDocumentId documentId } } Response: { "data": { "makeSecurityDocument": { "uploadInfo": { "url": "https://s3.amazonaws.com/documents.vertalo", "fields": { "key": "example/ed0b1825-b86c-4b0f-a2a0-2aff4eb18d34.pdf", "Content-Type": "application/pdf", "bucket": "documents.vertalo", "X-Amz-Algorithm": "AWS4-HMAC-SHA256", "X-Amz-Credential": "...2JXETTCGRODP/20220212/us-east-1/s3/aws4_request", "X-Amz-Date": "20220212T164558Z", "X-Amz-Security-Token": "IQoJb3JpZ2luX2VjEBQaCXVzLWVhc3QtMiJGME...p5kLZtLsrlro2vJQ==", "Policy": "eyJleHBpcmF0aW9uIjoiMjAyMi0wMi0xMlQxNzo0NTo1OFoiLCJjb25...szZHJBVRPT0ifV19", "X-Amz-Signature": "652018d81b2c8c48fc1585f3d1a...ed21e4aa2d24ac55cefdb8b0be2" } }, "securityDocumentId": "50846d44-537e-4e80-9ae9-1059b6d2195a", "accountDocumentId": null, "documentId": "ed0b1825-b86c-4b0f-a2a0-2aff4eb18d34" } } } Input parameters: name: file name extension: file extension without leading “. https://api.vertalo.com/docs/issuer/asset-configuration/create-asset/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/issuer/asset-configuration/create-asset/ Request: mutation { createAsset ( input: { asset: { name: "Example Asset #1" type: "Preferred Equity" authorizedTotal: "5000000" status: "Active" } } ) { asset { id } } } Response: { "data": { "createAsset": { "asset": { "id": "b29704fd-5613-4f16-b712-a942a126413b" } } } } Numeric field Usage authorizedTotal The total number of shares/units authorized for sale overall In this example, the mutation creates a new asset with the required properties. It also shows a return payload requested as part of the mutation. https://api.vertalo.com/docs/issuer/tokenization/initialize-token/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/issuer/tokenization/initialize-token/ Request: mutation { makeToken ( input: { _tokenId: "7ae8c3b7-43a4-4ee3-99c8-812e101d3859" _chain: "ethereum-vertalo" _name: "Series A Token" _symbol: "SERIESA" } ) { token { contractsByTokenId { nodes { id } } } } } Response: { "data": { "makeToken": { "token": { "contractsByTokenId": { "nodes": [ { "id": "48e2486f-a988-4f92-9794-4df831c03879" } ] } } } } } In this example, the mutation initializes a new token for a round. There is a one-to-one relationship between round and token, with a token ID being automatically assigned at the creation of a round. https://api.vertalo.com/docs/api-key/overview/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/api-key/overview/ 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. https://api.vertalo.com/docs/appendix/legacy/overview/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/appendix/legacy/overview/ As the Vertalo platform evolves, certain operations may change. In order to maintain backward compatability, these legacy operations (and the API call(s) associated with them) will remain in place for a period of time to be determined by Vertalo, and then deprecated. Prior to deprecation, those currently relying on these operations should use the following migration strategy: Update your code to the newer version of the operation. Deploy and test your updated code (in the your testing environment) using your Vertalo sandbox API keys, carefully verifying the updated operations using the Vertalo sandbox portal where appropriate. https://api.vertalo.com/docs/ats-exchange/overview/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/ats-exchange/overview/ 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. https://api.vertalo.com/docs/broker/overview/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/broker/overview/ The Vertalo platform offers support for organizations that assist issuers with their digital securities offerings, including: Broker-Dealers Registered Investment Advisors Capital Advisors Deal Packaging Consultants 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. https://api.vertalo.com/docs/coding-examples/overview/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/coding-examples/overview/ 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. https://api.vertalo.com/docs/custodian/overview/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/custodian/overview/ 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. https://api.vertalo.com/docs/issuer/overview/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/issuer/overview/ The actions for an issuer in a primary issuance context follow a typical ordering: Configure assets/rounds/allocations Create customers Record investment interest Record receipt of funds Issue securities Tokenize securities (optional) 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. https://api.vertalo.com/docs/introduction/welcome/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/introduction/welcome/ The Vertalo platform is a modern, blockchain-aware architecture that supports many functions, including: Digital asset configuration and management Investor onboarding (with KYC/AML, accreditation, document signing) Payment processing Cap table management Securities issuance Tokenization ATS integration General transfer agency services 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. https://api.vertalo.com/docs/api-key/authentication/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/api-key/authentication/ /authenticate/token/login Once you’ve been issued a client ID and client secret, you will be able to generate a bearer token which you will then use to associate your access with a specific role that has been configured for your account. Request: curl 'https://sandbox.vertalo.com/authenticate/token/login?client_id=<client ID>&client_secret=<client secret>' Response: { "token": { "token_type": "Bearer", "access_token": "<token>" }, "roles": { "data": [ { "last_name": "example", "user_role": "account_admin", "account_type": "broker", "account_name": "Example", "user_id": "<UUID>", "users_account_id": "<UUID>", "first_name": "admin", "account_id": "<UUID>", "slug": "example", "email": "admin@example. https://api.vertalo.com/docs/custodian/bulk-deposit/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/custodian/bulk-deposit/ Request: mutation { bulkDeposit ( input : { securityId: "" idempotencyId: "" deposit: [ { idempotencyId: "" depositAddressId: "" investorId: "" externalInvestorId: "" date: "" holdings: [ { id: "" amount: "" } ] signature: { status: "" signature: "" date: "" } investorInformation: { name: "" taxId: "" email: "" address: [ { lineOne: "" lineTwo: "" lineThree: "" lineFour: "" city: "" province: "" postalCode: "" country: "" } ] data: { field1: "" field2: "" } parties: [ { firstName: "" lastName: "" taxId: "" email: "" address: [ { lineOne: "" lineTwo: "" lineThree: "" lineFour: "" city: "" province: "" postalCode: "" country: "" } ] } ] } tags: [ { id: "" data: { field1: "" field2: "" } } ] fee: { currency: "" amount: "" } } ] } ) { id accountId securityId requestId type status createdOn executedOn requestByRequestId { data } } } Numeric field Usage deposit. https://api.vertalo.com/docs/appendix/conditions-filters/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/appendix/conditions-filters/ In previous examples, you will have noticed the use of the condition keyword at various points in the query, which provides a rudimentary means to filter for specific values. The Vertalo API also supports the filter keyword, which provides even more advanced capabilities. Request: query { allAccounts (condition: {type: "investor", email: "bob.smith@example.com"}) { nodes { id name email distributionsByInvestorId { nodes { amount allocationByAllocationId { name roundByRoundId { name assetByAssetId { name } } } } } } } } Response: { "data": { "allAccounts": { "nodes": [ { "id": "d6fb328d-2426-4689-98d0-8a0a03679a03", "name": "Bob Smith", "email": "bob. https://api.vertalo.com/docs/issuer/document-upload/holding-docucment/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/issuer/document-upload/holding-docucment/ Request: mutation { makeHoldingDocument( input: { name: "PPM", extension: "pdf", holdingId: "71ac4fd6-2877-46bd-a8b9-f76bca6d6dc4", shareWith: ["investor"] }) { uploadInfo holdingDocumentId accountDocumentId documentId } } Response: { "data": { "makeHoldingDocument": { "uploadInfo": { "url": "https://s3.amazonaws.com/documents.vertalo", "fields": { "key": "example/1c8e4025-2fbe-40ec-ba18-b910fb4db2f6.pdf", "Content-Type": "application/pdf", "bucket": "documents.vertalo", "X-Amz-Algorithm": "AWS4-HMAC-SHA256", "X-Amz-Credential": "...JXETTCGRODP/20220212/us-east-1/s3/aws4_request", "X-Amz-Date": "20220212T165022Z", "X-Amz-Security-Token": "IQoJb3JpZ2luX2VjEBQaCXVzLWVhkyl...g9Pp5kLZtLsrlro2vJQ==", "Policy": "eyJleHBpcmF0aW9uIjoiMjAyMi0wMi0xMlQxNzo...WtMWnRMc3Jscm8ydkpRPT0ifV19", "X-Amz-Signature": "ebe00453aded2a1c20bdafb...2129eddf5f42a50e45e77130aeeb1c0" } }, "holdingDocumentId": "75718a2b-81e5-4655-8c37-7a5f47a4be45", "accountDocumentId": null, "documentId": "1c8e4025-2fbe-40ec-ba18-b910fb4db2f6" } } } Input parameters: name: file name extension: file extension without leading “. https://api.vertalo.com/docs/issuer/asset-configuration/create-round/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/issuer/asset-configuration/create-round/ Request: mutation { makeRound ( input: { assetId: "b29704fd-5613-4f16-b712-a942a126413b" name: "Series A" opensOn: "2022-01-01" closesOn: "2022-03-31" total: "2000000" price: "1.00" status: "Active" termsUrl: "https://dataroom.example.com" } ) { round { id securityId tokenId } } } Response: { "data": { "makeRound": { "round": { "id": "3fb91ee2-eb13-4308-b4ca-1c968a6546a4", "securityId": "4a8b023d-ecfb-4889-9768-0f5a97f906c5", "tokenId": "7ae8c3b7-43a4-4ee3-99c8-812e101d3859" } } } } Numeric field Usage total The total number of shares/units authorized for sale in the round price The price per share/unit expressed in USD In this example, the mutation creates a new round that is associated with the asset created in the previous example. https://api.vertalo.com/docs/ats-exchange/create-investor/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/ats-exchange/create-investor/ Request: mutation { makeInvestor( input: { name: "John Jones" email: "john.jones@example.com" } ) { account { id } } } Response: { "data": { "makeInvestor": { "account": { "id": "9452007f-429c-478d-92f2-096b8e32b829" } } } } In this example, the mutation creates a new investor. This makes it possible for an ATS to pre-populate investors on the Vertalo platform prior to trading in order create efficiencies when trading eventually occurs. This is not a requirement, however, as new investors (those not already on the Vertalo platform) can be automatically created when trades are recorded. https://api.vertalo.com/docs/broker/create-issuer/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/broker/create-issuer/ Request: mutation { makeIssuerAccount ( input: { companyName: "Example Issuer" companyEmail: "mary.johnson@example.com" } ) { account { id type } } } Response: { "data": { "makeIssuerAccount": { "account": { "id": "a68a3ac2-5110-4207-9bad-e9acbdec6f1a", "type": "issuer" } } } } In this example, the mutation creates a new issuer. The ID of the newly created issuer is returned in the payload. You then have the option to switch to this issuer role and perform actions as the issuer. https://api.vertalo.com/docs/issuer/tokenization/deploy-contract/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/issuer/tokenization/deploy-contract/ Request: mutation { deployContract ( input: { _contractId: "48e2486f-a988-4f92-9794-4df831c03879" } ) { contract { contractAddress } } } Response: { "data": { "deployContract": { "contract": { "contractAddress": "0x6537d77941ef111b4c853d38a03fe9478bc36d41" } } } } In this example, the mutation deploys a smart contract (associated to a token) to the blockchain and returns the on-chain contract address in the payload. Note that the contract ID returned from the previous example of the initialization of a token is used in the deployment of the contract. https://api.vertalo.com/docs/appendix/legacy/issue-distributions/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/appendix/legacy/issue-distributions/ Request: mutation { issueDistributions ( input: { distributionIds: [ "8f444de2-bfd9-4ca5-b6f4-74c4e511cebc" ] } ) { issuanceEvents { holdingId } } } Response: { "data": { "issueDistributions": { "issuanceEvents": [ { "holdingId": "67ebd6a5-3ffa-4336-b683-31d1d4251a2c" } ] } } } In order to maintain backward compatability with the previous method of issuing distributions, the issueDistributions mutation will remain in place for a period of time to be determined. This mutation will eventually be fully deprecated, and those currently using it will have to migrate to the new method described in the section Request Distribution Issuance under Issuer Actions » Primary Issuance. https://api.vertalo.com/docs/coding-examples/python-example/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/coding-examples/python-example/ This example makes use of an open-source GraphQL client module for Python, gql. You must first install this module into your Python environment to use it, as well as other modules referenced if not already installed. import requests import json # # Import from GraphQL client library for Python... # from gql import gql, Client from gql.transport.aiohttp import AIOHTTPTransport # # Call token discovery endpoint... # response = requests.get("https://sandbox.vertalo.com/authenticate/token/discovery") # print(response. https://api.vertalo.com/docs/issuer/primary-issuance/record-payment/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/issuer/primary-issuance/record-payment/ Request: mutation { createDistributionPayment( input: { distributionPayment: { distributionId: "8f444de2-bfd9-4ca5-b6f4-74c4e511cebc" amount: "100000" } } ) { distributionPayment { id paidOn } } } Response: { "data": { "createDistributionPayment": { "distributionPayment": { "id": "1e0b807f-4d89-4331-92b7-f7beaf25617a", "paidOn": "2022-01-01T18:49:48.237216+00:00" } } } } In this example, the mutation records a payment against a distribution. The ID and paid-on date of the payment is returned in the payload. Note that the distribution ID returned from the previous example of the creation of a distribution is used in the recording of the payment. https://api.vertalo.com/docs/introduction/roles/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/introduction/roles/ 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 Description System Privileges Issuer A legal entity that registers and sells securities, with the purpose of generating income to fund operations. Create assets, rounds, allocations, distributions; manage investors; issue and tokenize holdings Broker A legal entity that assists with the distribution of an issuer’s offerings to investors, including broker-dealers, registered investment advisors, capital advisors. https://api.vertalo.com/docs/issuer/investor-setup/setup-customer/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/issuer/investor-setup/setup-customer/ Request: mutation { setupCustomer ( input: { name: "" email: "" accountSetupData: { type: "" formationDate: "" taxId: "" addresses: [ { lineOne: "" lineTwo: "" lineThree: "" lineFour: "" city: "" province: "" postalCode: "" country: "" type: "" } ] parties: [ { email: "" firstName: "" lastName: "" taxId: "" dateOfBirth: "" usCitizen: true isPrimary: true allowLogin: true addresses: [ { lineOne: "" lineTwo: "" lineThree: "" lineFour: "" city: "" province: "" postalCode: "" country: "" type: "" } ] } ] } } ) { customer { id investorId } } } The example above shows the full extent of the setupCustomer mutation, through which you submit details for a customer (investor). https://api.vertalo.com/docs/broker/accept-invite/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/broker/accept-invite/ Syndication As mentioned in the overview to this chapter, an issuer may choose to syndicate the fulfillment of a round by inviting brokers to participate. This is only possible in cases where the broker has created the issuer, either through the Vertalo portal or programmatically via the API (as described in the previous section). The issuer then (and only then) has the option to invite the broker to a round they have previously created. https://api.vertalo.com/docs/introduction/accounts-users/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/introduction/accounts-users/ 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. https://api.vertalo.com/docs/issuer/investor-setup/assign-wallet/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/issuer/investor-setup/assign-wallet/ Request: mutation { makeExternalBlockchainAddress ( input: { address: "0x71C7656EC7ab88b098defB751B7401B5f6d8976F" chain: "ethereum-mainnet" investorId: "a928056c-d33e-4960-8796-bf3c2af86b77" } ) { blockchainAddress { id } } } Response: { "data": { "makeExternalBlockchainAddress": { "blockchainAddress": { "id": "af495a87-4f1f-4694-ab57-69a3cbcb30de" } } } } In this example, a blockchain wallet address is assigned to an investor. The assumption is that an investor has created a self-sovereign wallet on a blockchain supported by Vertalo, and then provided it to the vendor who then passes it through to the Vertalo system. https://api.vertalo.com/docs/ats-exchange/batch-transfer/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/ats-exchange/batch-transfer/ Request: mutation { batchTransfer ( input: { idempotencyId: "" transfer: [ { idempotencyId: "" investorId: "" securityId: "" usdPrice: "" transferPrice: { currency: "" amount: "" } holdings: [ { id: "" amount: "" } ] signature: { status: "" signature: "" date: "" } investorInformation: { name: "" taxId: "" email: "" address: [ { lineOne: "" lineTwo: "" lineThree: "" lineFour: "" city: "" province: "" postalCode: "" country: "" } ] parties: [ { firstName: "" lastName: "" taxId: "" email: "" address: [ { lineOne: "" lineTwo: "" lineThree: "" lineFour: "" city: "" province: "" postalCode: "" country: "" } ] } ] data: { field1: "" field2: "" } } to: { id: "" email: "" name: "" jurisdiction: "" accountSetupData: { type: "" formationDate: "" taxId: "" addresses: [ { lineOne: "" lineTwo: "" lineThree: "" lineFour: "" city: "" province: "" postalCode: "" country: "" type: "" } ] parties: [ { email: "" firstName: "" lastName: "" taxId: "" dateOfBirth: "" usCitizen: true isPrimary: true allowLogin: true addresses: [ { lineOne: "" lineTwo: "" lineThree: "" lineFour: "" city: "" province: "" postalCode: "" country: "" type: "" } ] } ] } } tags: [ { id: "" data: { field1: "" field2: "" } } ] data: { field1: "" field2: "" } matchedOn: "" settledOn: "" } ] } ) { id requestId type status createdOn executedOn requestByRequestId { data } } } Numeric field Usage transfer. https://api.vertalo.com/docs/api-key/calling-graphql/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/api-key/calling-graphql/ /token/api/v2/graphql Using the response from the /token/role endpoint, use the value of the access_token field to construct a request to a single /token/api/v2/graphql endpoint through which you issue properly formed GraphQL queries and mutations to the Vertalo API. Request: curl --location --request POST 'https://sandbox.vertalo.com/token/api/v2/graphql' --header 'Authorization: Bearer <access_token>' --header 'Content-Type: application/json' --data-raw '{"query": "query {\n allAssets {\n nodes {\n name\n type\n status\n authorizedTotal\n}\n}\n}", "variables":{}}' Response: { "data": { "allAssets": { "nodes": [{ "name": "Example Preferred Equity", "type": "Preferred Equity", "status": "active", "authorizedTotal": "5000000" }] } } } https://api.vertalo.com/docs/issuer/asset-configuration/create-tranche/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/issuer/asset-configuration/create-tranche/ Request: mutation { makeTranche ( input: { assetId: "08baabd1-39ea-49be-9888-7755afe8b94a" name: "Tranche - AAA" opensOn: "2023-08-01" closesOn: "2023-12-31" total: "70000000" price: "1.00" status: "Active" termsUrl: "https://dataroom.example.com" coupon: "6.25" term: "3" } ) { round { id } } } Response: { "data": { "makeTranche": { "round": { "id": "a0471b97-5265-4fad-affa-f51637dfafe2" } } } } Numeric field Usage total The total number of shares/units authorized for sale in the tranche price The price per share/unit expressed in USD coupon The % return/yield on the investment term The duration of the investment If the asset in question is a debt instrument (a bond, for example), you will need to employ the makeTranche mutation rather than the makeRound mutation from the previous section due to the need for additional information (coupon and term). https://api.vertalo.com/docs/appendix/error-codes/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/appendix/error-codes/ Below is a list of current error codes produced by the Vertalo API. Code Description 1 Permission denied. 100 Invalid token name. 101 Invalid token symbol. 130 Token information cannot be edited once deployed. 210 Invalid blockchain registration method. 211 Invalid blockchain chain. 320 Allocation status cannot be edited once the issuance process begins. 330 Allocations must be closed in order to issue. 331 All holdings must be closed or locked before the allocation can close. https://api.vertalo.com/docs/issuer/document-upload/upload-example/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/issuer/document-upload/upload-example/ /** * Upload file to S3 with previously received pre-signed POST data. * @param presignedPostData * @param file * @returns {Promise<any>} */ const uploadFileToS3 = (presignedPostData, file) => { return new Promise((resolve, reject) => { const formData = new FormData(); Object.keys(presignedPostData.fields).forEach(key => { formData.append(key, presignedPostData.fields[key]); }); // Actual file has to be appended last. formData.append("file", file); const xhr = new XMLHttpRequest(); xhr.open("POST", presignedPostData.url, true); xhr.send(formData); xhr.onload = function() { this.status === 204 ? https://api.vertalo.com/docs/issuer/tokenization/mint-token/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/issuer/tokenization/mint-token/ Request: mutation { tokenizeHoldings ( input: { holdingIds: [ "67ebd6a5-3ffa-4336-b683-31d1d4251a2c" ] } ) { holdings { investorId issuedOn holdingBlockchainAddressesByHoldingId { nodes { blockchainAddressId blockchainAddressByBlockchainAddressId { address } } } } } } Response: { "data": { "tokenizeHoldings": { "holdings": [ { "investorId": "d6fb328d-2426-4689-98d0-8a0a03679a03", "issuedOn": "2021-12-16T22:05:46.253555+00:00", "holdingBlockchainAddressesByHoldingId": { "nodes": [ { "blockchainAddressId": "28978c2d-d5e6-498c-a462-fd19b803b8d2", "blockchainAddressByBlockchainAddressId": { "address": "0x99032ac273e339e3fd26e27d26146c0fe668b927" } } ] } } ] } } } In this example, the mutation mints tokens to investor wallets based on their holding IDs. https://api.vertalo.com/docs/coding-examples/php-example/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/coding-examples/php-example/ This example makes use of the cURL extension for PHP. This extension must be enabled in your PHP configuration to use it. <?php $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, "https://www.sandbox.vertalo.com/authenticate/token/discovery"); curl_exec($ch); curl_close($ch); // // Get LOGIN access token... // $client_id = "<your client ID>"; $client_secret = "<your client secret>"; curl_setopt($ch, CURLOPT_URL, "https://www.sandbox.vertalo.com/authenticate/token/login?client_id=$client_id&client_secret=$client_secret"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch); $response = json_decode($response, true); $access_token = $response["token"]["access_token"]; $users_account_id = $response["roles"]["data"][0]["users_account_id"]; // print("$access_token\n"); // print("$users_account_id\n"); // // Get ROLE access token. https://api.vertalo.com/docs/custodian/all-requests/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/custodian/all-requests/ Request: query { allRequests { nodes { id accountId data type createdOn stagedTransfersByRequestId { nodes { id accountId securityId type status webhookId data createdOn executedOn } } } } } In this example, the query returns ALL requests submitted by the custodian using the bulkDeposit mutation documented in this chapter. Standard GraphQL conditions/filters may be applied to this type of query in order limit the size of the result set. See the Appendix for more details. https://api.vertalo.com/docs/issuer/primary-issuance/update-distribution/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/issuer/primary-issuance/update-distribution/ Request: mutation { updateDistributionById ( input: { id: "8f444de2-bfd9-4ca5-b6f4-74c4e511cebc" distributionPatch: {status: "closed"} } ) { distribution { id status } } } Response: { "data": { "updateDistributionById": { "distribution": { "id": "8f444de2-bfd9-4ca5-b6f4-74c4e511cebc", "status": "closed" } } } } When a distribution is initially created for an investor the status of the distribution is set to “drafted”, indicating that this is a pro forma distribution that the issuer will approve in order to allow the investor to proceed through the investment process. https://api.vertalo.com/docs/broker/create-delegate/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/broker/create-delegate/ Request: mutation { makeDelegate ( input: { firstName: "Some" lastName: "Delegate" email: "some.delegate@example.com" role: "account_admin" } ) { usersAccount { userId role status } } } Response: { "data": { "makeDelegate": { "usersAccount": { "userId": "f24dbbea-742c-4513-96e9-6b2f4edadcc3", "role": "account_admin", "status": "active" } } } } In this example, the migration adds a delegate to the account role under whose authority you are operating. Possible values for the “role” field in the mutation are: https://api.vertalo.com/docs/issuer/asset-configuration/create-allocation/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/issuer/asset-configuration/create-allocation/ Request: mutation { createAllocation ( input: { allocation: { roundId: "3fb91ee2-eb13-4308-b4ca-1c968a6546a4" name: "Domestic Investors" opensOn: "2022-01-01" closesOn: "2022-03-31" } } ) { allocation { id } } } Response: { "data": { "createAllocation": { "allocation": { "id": "abb668d2-63d2-43dd-b495-b1e413a69427" } } } } An allocation is a grouping of distributions within a round that allows the issuer to distinguish groups of investors within a round, for example, domestic vs other, or tokenized vs non-tokenized. https://api.vertalo.com/docs/appendix/introspection/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/appendix/introspection/ The entirety of the Vertalo GraphQL schema is available for you to explore through the GraphiQL interactive tool described in the Getting Going section of the Introduction. The tool itself leverages a very powerful feature of GraphQL, called “introspection”, through which you can ask the schema for information on what queries, mutations, and subscriptions it supports. Here is a query you can utilize to perform this action: query IntrospectionQuery { __schema { queryType { name } mutationType { name } subscriptionType { name } types { . https://api.vertalo.com/docs/introduction/multi-tenancy/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/introduction/multi-tenancy/ 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. https://api.vertalo.com/docs/issuer/primary-issuance/request-distribution-issuance/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/issuer/primary-issuance/request-distribution-issuance/ Request: mutation { makeTaRequestDistributionIssuances( input: { distributionIds: [ "8f444de2-bfd9-4ca5-b6f4-74c4e511cebc", "450bf0ea-4dbf-4f1d-b82d-12005186b48c", "cd84c96d-2f85-4737-ba85-9882a71f35ac" ] } ) { taRequests { id distributionId stagedTransferId investorId status createdOn } } } Response: { "data": { "makeTaRequestDistributionIssuances": { "taRequests": [ { "id": "28eb5562-2cd2-4672-bd4c-537fe7274227", "distributionId": "8f444de2-bfd9-4ca5-b6f4-74c4e511cebc", "stagedTransferId": "637e3e6d-856b-4a95-ac78-f0cfc6a5b28f", "investorId": "9f93a40d-c243-40aa-839b-f1c711e21206", "status": "pending", "createdOn": "2024-09-04T23:12:18.204916+00:00" }, { "id": "487cdd54-752d-4806-817f-ce20033352b1", "distributionId": "450bf0ea-4dbf-4f1d-b82d-12005186b48c", "stagedTransferId": "5eaaa02f-8021-4e58-aabd-03baa8ba7035", "investorId": "cf6ba744-94fc-4173-99e3-d2387229f434", "status": "pending", "createdOn": "2024-09-04T23:12:18.204916+00:00" }, { "id": "3f1ba2f6-6301-4882-9095-6423373c2dc0", "distributionId": "cd84c96d-2f85-4737-ba85-9882a71f35ac", "stagedTransferId": "737b2015-af78-4c98-a9fe-4d1c0e5594d6", "investorId": "c120ca44-e1b5-47d7-9fed-5d161981f40c", "status": "pending", "createdOn": "2024-09-04T23:12:18. https://api.vertalo.com/docs/ats-exchange/useful-queries/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/ats-exchange/useful-queries/ Query Securities Request: query { allSecurities { nodes { id holdingsBySecurityId { nodes { id investorId amount createdOn accountByInvestorId { id name email } } } } } } Response: { "data": { "allSecurities": { "nodes": [ { "id": "6a93a168-31b6-4a67-b9f9-8cda51e5e6ba", "holdingsBySecurityId": { "nodes": [ { "id": "67ebd6a5-3ffa-4336-b683-31d1d4251a2c", "investorId": "d6fb328d-2426-4689-98d0-8a0a03679a03", "amount": "100000.000000000000000000", "createdOn": "2021-12-16T22:05:46.253555+00:00", "accountByInvestorId": { "id": "d6fb328d-2426-4689-98d0-8a0a03679a03", "name": "Bob Smith", "email": "bob.smith@example.com" } } ] } } ] } } } In this example, the query fetches all securities (and respective holdings) for which you are the listing ATS. https://api.vertalo.com/docs/introduction/getting-going/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/introduction/getting-going/ 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 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: https://api.vertalo.com/docs/issuer/asset-configuration/invite-broker/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/issuer/asset-configuration/invite-broker/ Request: mutation { createBrokerAllocation ( input: { brokerAllocation: { brokerId: "2bfdb931-d934-4b51-8226-b392f579cef2" roundId: "59671b88-9b68-428c-b2f5-c3ebe0cc705c" } } ) { brokerAllocation { id managedUnits invitationStatusByStatus { status } } } } Response: { "data": { "createBrokerAllocation": { "brokerAllocation": { "id": "421737dc-3b00-47dc-b147-2f9c0db7c953", "managedUnits": "0", "invitationStatusByStatus": { "status": "sent" } } } } } In this example, an issuer is syndicating the fulfillment of a specific round by creating what’s known as a broker allocation. This is effectively an invitation to a broker to participate in the fulfillment of that round. https://api.vertalo.com/docs/issuer/primary-issuance/request-issuance/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/issuer/primary-issuance/request-issuance/ Request: mutation { makeTaRequestIssuance ( input: { securityId: "0994921c-647f-4809-823c-2cd20ac7646b" toAccountId: "ce47dc3e-10f0-4ce1-beb9-b74debb144ac" amount: "20000" costBasis: "5.00" issuanceDate: "2023-01-01" } ) { taRequest { id status createdOn } } } Response: { "data": { "makeTaRequestIssuance": { "taRequest": { "id": "740cffb4-ae5a-4256-8083-c9ecad4f6f94", "status": "pending", "createdOn": "2023-07-20T22:26:36.247596+00:00" } } } } Numeric field Usage amount The total number of units/shares costBasis The per unit/share price It may be the case that an issuer has an existing cap table based on the prior issuance of a security to a set of investors, that they then want to bring to the Vertalo platform. https://api.vertalo.com/docs/appendix/vsp-overview/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/appendix/vsp-overview/ The Vertalo Securities Protocol (VSP) is a standardized smart-contract architecture that gives private issuers flexibility in their offerings and tokenizations. Built upon a proprietary technology that Vertalo developed for its own STO in 2018, it can implement any trading-restriction policy from full lockup to free trading, and can be upgraded at any future date to change the restrictions. As a regulated entity in its capacity as a licensed transfer agent, Vertalo works to ensure the movement and custodying of digital securities (using VSP) in a regulatory compliant manner for the benefit of our clients. https://api.vertalo.com/docs/introduction/object-model/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/introduction/object-model/ The Vertalo object model consists of the following major components: Users Accounts Assets Rounds Allocations Investors Distributions Securities Holdings 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: Issuers (which manage) Assets (which contain) Rounds (which contain) Allocations (which contain) Investors (which hold) Distributions The basic post-issuance object hierarchy is: https://api.vertalo.com/docs/introduction/partner-integrations/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/introduction/partner-integrations/ As a digital transfer agent, Vertalo sits at the intersection of a digital asset ecosystem that includes key partners providing the following services: KYC/AML Accreditation Document signing Payment Processing Trade order matching Custody/Escrow 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. https://api.vertalo.com/docs/introduction/postgraphile/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/introduction/postgraphile/ 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. https://api.vertalo.com/docs/introduction/internal-blockchain/ Tue, 28 Jan 2020 00:39:09 +0900 https://api.vertalo.com/docs/introduction/internal-blockchain/ 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.