Vulcan Forge
  1. Financial Instruments
Vulcan Forge
  • Introduction
  • Getting Started
  • Authentication & Authorization
  • Core Concepts
    • Terminology
    • Regulated Assets
    • Tenants
    • Mapping & Labelling
    • Solana Networks
    • Transaction Processing
    • Key Management
    • Read Layer
  • API Reference
    • Blockchain Accounts
      • Create Account
      • Fetch Account Details
      • Fetch Account Balance
      • Fetch Account Private Key
      • Fetch Accounts
      • Update Account
      • Inactivate Account
    • Financial Instruments
      • Create Financial Instrument
        POST
      • Fetch Financial Instrument Details
        POST
      • Fetch Financial Instruments
        POST
      • Update Financial Instrument
        PATCH
      • Token Extensions Calculator
        POST
    • Positions
      • State
        • Initialize Position
        • Update Position
        • Close Position
        • Freeze Position
        • Unfreeze Position
      • Movements
        • Mint
        • Burn
        • Transfer Financial Instrument
        • Transfer SOL
      • Trades
        • Trade
      • History
        • Fetch Positions
        • Fetch Position Details
        • Fetch Position Balance
    • Loans
      • Create Loan
      • Fetch Loan Details
      • Fetch Loans
      • Swap Collateral
      • Repay Loan
      • Close Loan
      • Refinance Loan
    • Blockchain Transactions
      • Processing
        • Fetch Transaction Status
        • Sign Transaction
        • Submit Transaction
      • Durable Nonces
        • Create Durable Nonce Accounts
        • Fetch Durable Nonce Account Details
        • Fetch Durable Nonce Accounts
      • Address Lookup Tables
        • Create Address Lookup Table
        • Fetch Address Lookup Table Details
        • Fetch Address Lookup Tables
        • Extend Address Lookup Table
        • Update Address Lookup Table
      • History
        • Fetch Transactions
        • Fetch Transaction Details
    • Market Data
      • Onchain Data Sources
        • Create Onchain Data Source
        • Update Oracle Data Source Definition
        • Refresh Oracle Data Source
        • Fetch Onchain Data Source Details
        • Fetch Oracle Data Sources
  • Schemas
    • Accounts
      • DKG
        • DKG Key Setup
      • Offchain References
      • Account Lookup
      • New Account
      • Debit Limit Config
      • Limit Duration
      • Tenancy Config
      • Account Debits Config
      • Account Balance
      • Offchain File
    • Transactions
      • Solana Transaction Config
      • Commitment Config
      • Transaction Lookup
    • Query
      • Query Components
        • Sort Model
        • Field Value Filter
        • Filter Model
      • Items Query
      • Bulk Query
    • Loans
      • Loan Duration
    • Reponses
      • Errors
        • Individual Error
        • Error Response
      • Accounts
        • Private Keys
          • Private Key Details
          • Database Private Key Details
          • Cloud Provider Resource Location
          • DKG Private Key Details
        • Account Response Detailed
        • Account Onchain Detailed
        • Account Offchain Detailed
        • Account Response Identifiers
        • Account Offchain Compact
        • Account Response Compact
        • Account Onchain Compact
      • Financial Instruments
        • Financial Instrument Detailed
        • Financial Instrument Compact
        • Financial Instrument Identifiers
      • Transactions
        • Solana Transaction Result
        • Solana Entity Result
      • Positions
        • Position Offchain Result
        • Position Balance Response
        • Position Response Detailed
        • Position Response Compact
        • Position Response Identifiers
      • Loans
        • Loan Response
      • Market Data
        • Onchain Data Source Response
    • Positions
      • Position Lookup
      • Transfer SOL Definition
      • Transfer Financial Instrument Definition
      • Burn Definition
      • Mint Definition
      • Position Debits Config
      • Position Balance
    • Loans
    • Market Data
      • Onchain Data Source Details
      • Switchboard details
  1. Financial Instruments

Create Financial Instrument

Testing
Development
https://vf-solana-api.dev.alphaledger.com
Development
https://vf-solana-api.dev.alphaledger.com
POST
/api/v1/financial-instruments
Creates Solana Transaction:If Requested
OperationId:createFinancialInstrument
Creates/onboards a financial instrument on the Vulcan Forge platform and onchain (optional). Use the itemData.alreadyOnchain=true setting to only onboard the financial instrument into Vulcan Forge but not submit a Solana transaction to create the financial instrument on the network (because the token/financial instrument is already full setup on the network).
Either of these 2 types of Solana tokens can be used to represent a financial instrument - see the version field in the request payload itemData:
SPL Token
Token 2022 (or Token Extensions)
Both the SPL Token and Token 2022 allows setting up a freeze authority which can freeze any token burn / mint / transfer activity:
for all positions (token accounts) for the SPL Token
on a per position basis for the Token 2022
For the Token 2022 financial instrument the following extensions are supported:
ExtensionDescriptionRequired at Creation
Metadata PointerEnables a mint account to specify the address of its metadata account.
Token MetadataAllows storage of metadata in the mint account. Requires for the metadata pointer to point to the mint account itself.
Default Account StateSets a default state for all new token accounts created for a mint.
Permanent DelegateAssigns an irrevocable delegate with authority over all token accounts and all activities for a mint.
Close MintEnables mint accounts to be closed and their rent reclaimed.
PausableAllows the pausable authority to stop all transactions on the token.
Scaled UI AmountAllows issuers to apply an updatable multiplier to the UI amount of a token.
Confidential TransferAllows transfers between token accounts without revealing the transfer amount.
Confidential Mint and BalancesAllows mints and burns without revealing the amount. Requires for the Confidential Transfer to be enabled. Thus position balances are confidential as well.
Trasnfer HookAllows for the execution of a custom program when a transfer occurs.
Note that if one tries to enable most or all of these extensions, the create token Solana transaction will fail as it will exceed the current maximum allowed transaction size. Workarounds available:
Use the Create Account endpoint to create the mint account ahead of time; In this case you would need to compute the required size for the mint account and specify that data size in the Create Account request payload. And use the itemData.existingMintAccount on the Create Financial Instrument request payload. Use the Token Extensions Calculator to estimate the mint account data size and minium required rent in SOL.
Do not add metadata fields (in offchain.simpleCustomMetadata) instead use the Update Financial Instrument to add the metadata fields after creation.
Note that while the Confidential Tranfer and Confidential Mint and Balances extensions can be enabled on a token, their usage on devnet and mainnet are not possible at the moment - the Solana programs associated with them are under a security audit review.

Request

Authorization
Bearer Token
Provide your bearer token in the
Authorization
header when making requests to protected resources.
Example:
Authorization: Bearer ********************
or
Query Params

Header Params

Body Params application/json

Examples

Responses

🟢201Created
application/json
Body

🟠400Bad Request
🟠401Unauthorized
🟠403Forbidden
🟠409Record Exists Already
🟠429Too Many Requests
🔴500Internal Server Error
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request POST 'https://vf-solana-api.dev.alphaledger.com/api/v1/financial-instruments?solanaClusterId=SOLANA_DEVNET' \
--header 'x-request-id: f9860f73-a466-41f2-a083-34eeb1cc3a3c' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "itemData": {
        "mintAccount": {
            "managed": true,
            "alreadyOnchain": false,
            "onchainId": "5ppHUtrk8vZjRdhwsYXJEPKwEPjazsMDyfBvJbhjmyah",
            "offchainReferences": {
                "alId": "ALFNDPF000153778",
                "organizationExternalId": "ALT",
                "accountNumber": "ALT10000233",
                "code": "some-authority",
                "type": "WALLET",
                "name": "Additional info related to the offchain reference"
            },
            "privateKeyDetails": {
                "location": [
                    "DATABASE"
                ],
                "publickKey": "5ppHUtrk8vZjRdhwsYXJEPKwEPjazsMDyfBvJbhjmyah",
                "privateKey": "EB46eeJToBz34ifceU1sYXWeferhcvaS28RsmQe9khX2Sv87wEnGgYbYC6deyhYSFVusxFvjKud2VTu6p2aCG9A",
                "dkgKeys": [
                    {
                        "keyUsage": "INV_TRADING_FX",
                        "useBackendPlayersCodes": [
                            "alt",
                            "alt"
                        ],
                        "isDefault": false,
                        "session": {
                            "threshold": 2
                        }
                    }
                ]
            },
            "solDebitApiKeys": [
                "abcd"
            ],
            "tokenDebitApiKeys": [
                "string"
            ],
            "debitLimits": [
                {
                    "applicableTo": "TOKEN",
                    "operationType": "ANY",
                    "destination": "ANY",
                    "mintAuthority": "ANY",
                    "maxAllowedDebit": {
                        "limitType": "PER_OPERATION",
                        "limitAmount": 100,
                        "duration": {
                            "code": "DAYS",
                            "unit": 1
                        },
                        "approversForOverride": [
                            "string"
                        ],
                        "requiredApproversCount": 2
                    }
                }
            ],
            "dataLength": 0,
            "seedSol": 0.087,
            "subscribeToNetworkEvents": true,
            "canPayFees": false,
            "globalFeePayerForOrgs": [
                "ALT"
            ],
            "orgsAllowedToSignWithPrivateKey": [
                "ALT"
            ],
            "shareAcrossTenants": false,
            "tokenVersion": "SPL",
            "comments": "Additional information about this account",
            "isDerived": false,
            "isGenesis": false,
            "domain": "vulcan-forge.sol",
            "skipBlockchainExistenceVerification": false
        },
        "existingMintAccount": {
            "onchainId": "GPjDgRPhSuJSya5GbaCWkYCDqcyL6N3ZBge9XMJsDton",
            "offchainId": "1b03ae9a-348c-4c18-8727-20c7c4ae7a0a",
            "offchainReferences": {
                "alId": "ALFNDPF000153778",
                "organizationExternalId": "ALT",
                "accountNumber": "ALT10000233",
                "code": "some-authority",
                "type": "WALLET"
            },
            "autoSign": true,
            "otherTenantOrganizationExternalId": "ALIM",
            "offPlatform": false
        },
        "mintAuthority": {
            "onchainId": "GPjDgRPhSuJSya5GbaCWkYCDqcyL6N3ZBge9XMJsDton",
            "offchainId": "1b03ae9a-348c-4c18-8727-20c7c4ae7a0a",
            "offchainReferences": {
                "alId": "ALFNDPF000153778",
                "organizationExternalId": "ALT",
                "accountNumber": "ALT10000233",
                "code": "some-authority",
                "type": "WALLET"
            },
            "autoSign": true,
            "otherTenantOrganizationExternalId": "ALIM",
            "offPlatform": false
        },
        "version": "TOKEN_2022",
        "alreadyOnChain": false,
        "updateAuthority": {
            "onchainId": "GPjDgRPhSuJSya5GbaCWkYCDqcyL6N3ZBge9XMJsDton",
            "offchainId": "1b03ae9a-348c-4c18-8727-20c7c4ae7a0a",
            "offchainReferences": {
                "alId": "ALFNDPF000153778",
                "organizationExternalId": "ALT",
                "accountNumber": "ALT10000233",
                "code": "some-authority",
                "type": "WALLET"
            },
            "autoSign": true,
            "otherTenantOrganizationExternalId": "ALIM",
            "offPlatform": false
        },
        "onchainData": {
            "symbol": "T12",
            "name": "Alphaledger/Simplify Target 12% Distribution Fund (T12)",
            "simpleCustomMetadata": {},
            "decimals": 0
        },
        "offchainData": {
            "description": "string",
            "simpleCustomMetadata": {},
            "logo": {
                "copyFromUri": "images/icon-fund-token-T12.png",
                "fileName": "icon-fund-token-T12.png",
                "contentType": "image/png",
                "type": "LOGO"
            },
            "complexCustomMetadata": {}
        },
        "freezeAuthority": {
            "onchainId": "GPjDgRPhSuJSya5GbaCWkYCDqcyL6N3ZBge9XMJsDton",
            "offchainId": "1b03ae9a-348c-4c18-8727-20c7c4ae7a0a",
            "offchainReferences": {
                "alId": "ALFNDPF000153778",
                "organizationExternalId": "ALT",
                "accountNumber": "ALT10000233",
                "code": "some-authority",
                "type": "WALLET"
            },
            "autoSign": true,
            "otherTenantOrganizationExternalId": "ALIM",
            "offPlatform": false
        },
        "defaultPositionState": "INITIALIZED",
        "permanentDelegateAuthority": {
            "onchainId": "GPjDgRPhSuJSya5GbaCWkYCDqcyL6N3ZBge9XMJsDton",
            "offchainId": "1b03ae9a-348c-4c18-8727-20c7c4ae7a0a",
            "offchainReferences": {
                "alId": "ALFNDPF000153778",
                "organizationExternalId": "ALT",
                "accountNumber": "ALT10000233",
                "code": "some-authority",
                "type": "WALLET"
            },
            "autoSign": true,
            "otherTenantOrganizationExternalId": "ALIM",
            "offPlatform": false
        },
        "closingAuthority": {
            "onchainId": "GPjDgRPhSuJSya5GbaCWkYCDqcyL6N3ZBge9XMJsDton",
            "offchainId": "1b03ae9a-348c-4c18-8727-20c7c4ae7a0a",
            "offchainReferences": {
                "alId": "ALFNDPF000153778",
                "organizationExternalId": "ALT",
                "accountNumber": "ALT10000233",
                "code": "some-authority",
                "type": "WALLET"
            },
            "autoSign": true,
            "otherTenantOrganizationExternalId": "ALIM",
            "offPlatform": false
        },
        "pausableAuthority": {
            "onchainId": "GPjDgRPhSuJSya5GbaCWkYCDqcyL6N3ZBge9XMJsDton",
            "offchainId": "1b03ae9a-348c-4c18-8727-20c7c4ae7a0a",
            "offchainReferences": {
                "alId": "ALFNDPF000153778",
                "organizationExternalId": "ALT",
                "accountNumber": "ALT10000233",
                "code": "some-authority",
                "type": "WALLET"
            },
            "autoSign": true,
            "otherTenantOrganizationExternalId": "ALIM",
            "offPlatform": false
        },
        "paused": false,
        "scaledUiAmountMultiplier": 2,
        "scaledUiAmountAuthority": {
            "onchainId": "GPjDgRPhSuJSya5GbaCWkYCDqcyL6N3ZBge9XMJsDton",
            "offchainId": "1b03ae9a-348c-4c18-8727-20c7c4ae7a0a",
            "offchainReferences": {
                "alId": "ALFNDPF000153778",
                "organizationExternalId": "ALT",
                "accountNumber": "ALT10000233",
                "code": "some-authority",
                "type": "WALLET"
            },
            "autoSign": true,
            "otherTenantOrganizationExternalId": "ALIM",
            "offPlatform": false
        },
        "transferHookAuthority": {
            "onchainId": "GPjDgRPhSuJSya5GbaCWkYCDqcyL6N3ZBge9XMJsDton",
            "offchainId": "1b03ae9a-348c-4c18-8727-20c7c4ae7a0a",
            "offchainReferences": {
                "alId": "ALFNDPF000153778",
                "organizationExternalId": "ALT",
                "accountNumber": "ALT10000233",
                "code": "some-authority",
                "type": "WALLET"
            },
            "autoSign": true,
            "otherTenantOrganizationExternalId": "ALIM",
            "offPlatform": false
        },
        "transferHookProgram": {
            "onchainId": "GPjDgRPhSuJSya5GbaCWkYCDqcyL6N3ZBge9XMJsDton",
            "offchainId": "1b03ae9a-348c-4c18-8727-20c7c4ae7a0a",
            "offchainReferences": {
                "alId": "ALFNDPF000153778",
                "organizationExternalId": "ALT",
                "accountNumber": "ALT10000233",
                "code": "some-authority",
                "type": "WALLET"
            },
            "autoSign": true,
            "otherTenantOrganizationExternalId": "ALIM",
            "offPlatform": false
        },
        "confidentialTransferAuthority": {
            "onchainId": "GPjDgRPhSuJSya5GbaCWkYCDqcyL6N3ZBge9XMJsDton",
            "offchainId": "1b03ae9a-348c-4c18-8727-20c7c4ae7a0a",
            "offchainReferences": {
                "alId": "ALFNDPF000153778",
                "organizationExternalId": "ALT",
                "accountNumber": "ALT10000233",
                "code": "some-authority",
                "type": "WALLET"
            },
            "autoSign": true,
            "otherTenantOrganizationExternalId": "ALIM",
            "offPlatform": false
        },
        "confidentialTransferAutoapproveNewAccounts": true,
        "confidentialMintBurnAuthority": {
            "onchainId": "GPjDgRPhSuJSya5GbaCWkYCDqcyL6N3ZBge9XMJsDton",
            "offchainId": "1b03ae9a-348c-4c18-8727-20c7c4ae7a0a",
            "offchainReferences": {
                "alId": "ALFNDPF000153778",
                "organizationExternalId": "ALT",
                "accountNumber": "ALT10000233",
                "code": "some-authority",
                "type": "WALLET"
            },
            "autoSign": true,
            "otherTenantOrganizationExternalId": "ALIM",
            "offPlatform": false
        },
        "addExtraRentLamports": 223455
    },
    "solanaTransactionConfig": {
        "feePayer": {
            "onchainId": "GPjDgRPhSuJSya5GbaCWkYCDqcyL6N3ZBge9XMJsDton",
            "offchainId": "1b03ae9a-348c-4c18-8727-20c7c4ae7a0a",
            "offchainReferences": {
                "alId": "ALFNDPF000153778",
                "organizationExternalId": "ALT",
                "accountNumber": "ALT10000233",
                "code": "some-authority",
                "type": "WALLET"
            },
            "autoSign": true,
            "otherTenantOrganizationExternalId": "ALIM",
            "offPlatform": false
        },
        "computeUnitConfig": {
            "enable": true,
            "limit": 1400000,
            "price": 35000,
            "priceEstimate": {
                "provider": "HELIUS",
                "calculationStrategy": "DEFAULT",
                "priorityLevel": "RECOMMENDED"
            }
        },
        "commitmentConfig": {
            "commitmentLevel": "processed"
        },
        "messageLifetimeStrategy": "RECENT_BLOCKHASH",
        "transactionVersion": "V0"
    },
    "tenancyConfig": {
        "overrideOrganizationExternalId": "ALIM"
    }
}'
Response Response Example
201 - SPL Token - USDC Already Onchain
// SPL Token - USDC Already Onchain
{
    "itemData": {
        "version": "SPL",
        "alreadyOnchain": true,
        "mintAccount": {
            "managed": false,
            "alreadyOnchain": true,
            "shareAcrossTenants": true,
            "comments": "USDC Token",
            "onchainId": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
            "offchainReferences": {
                "code": "{{usdc_al_id}}",
                "type": "CURRENCY_TOKEN",
                "alId": "{{usdc_al_id}}"
            }
        },
        //here we would have already onboarded the mint authority for USDC as another alreadyOnchain account with the offchain references that follow
        "mintAuthority": {
            "offchainReferences": {
                "code": "mint-db",
                "type": "TOKEN_MANAGEMENT_AUTHORITY",
                "organizationExternalId": "ALIM"
            }
        },
        //here we would have already onboarded the mint authority for USDC as another alreadyOnchain account with the offchain references that follow
        "updateAuthority": {
            "offchainReferences": {
                "code": "usdc-update",
                "type": "TOKEN_MANAGEMENT_AUTHORITY",
                "organizationExternalId": "VFS"
            }
        }
    }
}
Modified at 2026-01-05 00:03:11
Previous
Financial Instruments
Next
Fetch Financial Instrument Details
Built with