Vulcan Forge
    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
        • Update Financial Instrument
        • Fetch Financial Instrument Details
        • Fetch Financial Instruments
        • Token Extensions Calculator
      • Positions
        • State
          • Initialize 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
        • Update Feed
    • Schemas
      • Accounts
        • DKG
          • DKG Key Setup
        • Offchain References
        • Account Lookup
        • New Account
        • Tenancy 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
      • 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
        • Transactions
          • Solana Transaction Result
          • Solana Entity Result
        • Positions
          • Position Offchain Result
      • Positions
        • Position Lookup
        • Transfer Financial Instrument Definition
        • Burn Definition
        • Mint Definition
        • Transfer SOL Definition
        • Position Balance
      • Loans
        • Loan Duration

    Authentication & Authorization

    API Keys#

    Vulcan Forge uses API Keys for authenticating client applications that integrate with it.
    64-bytes API keys will be provided for the alpha release; to be used as Bearer tokens in the Authorization header
    HMAC API Keys to be made available with the beta release and for the production rollout.
    Each API Key is associated with one and only one Organization within a Vulcan Forge tenant.

    Authorization#

    The following roles can be attached to an API Key:
    Role NameDescription
    VULCAN_FORGE_ADMINCan access all endpoints and perform any operation (w/ the exception of access to the clear text private key), within the context of the data (blockchain entities/transactions) associated with the Tenant/Organization(s) that the API Key is mapped to
    VULCAN_FORGE_WRITEProvides access to all endpoints that write data onchain and/or offchain
    VULCAN_FORGE_WRITE_OFFCHAINThe system denies access if a write operation results on onchain data updates
    VULCAN_FORGE_READProvides access only to read layer endpoints - i.e. the Fetch endpoints
    VULCAN_FORGE_ALL_ORGS_IN_TENANT_SIGNINGAllows the user attached to the authenticated API Key to fetch private keys and sign transactions with them, even if these keys are associated with accounts that belong to another organization, as long as that organization is part of the same tenant associated with the API Key (appplicable only to Multi-org tenants)
    VULCAN_FORGE_SENSITIVE_DATA_ACCESSThe only role that provides access to the Fetch Account Private Key endpoint
    VULCAN_FORGE_UPDATE_DEBIT_API_KEYSThe only role that allows changes of the solDebitApiKeys and tokenDebitApiKeys fields on Accounts and Positions

    API Key Identifier#

    Optionally, the API Key can be setup with an identifier that matches this regex pattern: ^[a-z0-9-]{4,20}$. The API Key Identifier has to be unique within the scope of its associated tenant.
    Use case for it: to restrict debit operations of SOL or tokens only to requests that are associated with the API Keys with Identifiers setup in the solDebitApiKeys or tokenDebitApiKeys fields. When set, these fields will hold a whitelist of API Key Identifiers.
    These fields can be setup at the following levels - 2nd level overides the 1st level setting:
    IDLevel DescriptionFields Supported
    1Blockchain Account Type:
    • WALLET
    • CURRENCIES_WALLET
    • ASSETS_WALLET
    • DEFI_SETTLEMENT_WALLET
    • solDebitApiKeys
    • tokenDebitApiKeys
    2Blockchain Account Type:
    • ASSETS_POSITION
    • CURRENCIES_POSITION
    • tokenDebitApiKeys
    At level 2, the tokenDebitApiKey can also be set to a value of any -> it overiddes the level 1 setting and allows any API Key Identifier to do a debit, as long as that API Key is linked through the tenant/orgs associations with the blockchain entities that will have balances debited.
    The Create Account and Initialize Position are examples of endpoints where the solDebitApiKeys and tokenDebitApiKeys can be set. The lists can hold a maximum of 10 identifiers.
    Note that when intializing or updating a position, if the owner account on the position has a tokenDebitApiKeys set, the API Key performing the initialize/update has to be part of the list in tokenDebitApiKeys of the owner wallet, if a tokenDebitApiKeys is to be set at the position level.
    In addition, the VULCAN_FORGE_UPDATE_DEBIT_API_KEYS role has to be associated with an API Key in order to allow it to change the solDebitApiKeys and/or tokenDebitApiKeys fields, either at the Account or Position level.
    SOL Debits Examples
    #Level IDLevel DescriptionTransfer 1Transfer 2Transfer 3
    API KeyAllowedAPI KeyAllowedAPI KeyAllowed
    11Source Wallet solDebitApiKeys: ['abcd', 'efgh']abcd efgh wxyz
    21Source Wallet solDebitApiKeys: Not Setabcd efgh wxyz
    Token Debits Examples
    #Level IDLevel DescriptionTransfer 1Transfer 2Burn 1Burn 2
    API KeyAllowedAPI KeyAllowedAPI KeyAllowedAPI KeyAllowed
    11Source Wallet tokenDebitApiKeys: ['abcd', 'efgh']lmno abcd wxyz efgh 
    2Source Position tokenDebitApiKeys: ['abcd', 'wxyz']
    21Source Wallet tokenDebitApiKeys: ['abcd', 'efgh']lmno abcd wxyz efgh 
    2Source Position tokenDebitApiKeys: ['any']
    32Source Position tokenDebitApiKeys: ['pqrs']abcd klmn pqrswzyz
    41Source Wallet tokenDebitApiKeys: ['abcd']abcd klmn pqrswzyz
    51Source Wallet tokenDebitApiKeys: Not Setlmno abcd wxyz efgh 
    2Source Position tokenDebitApiKeys: Not Set

    Client IP restrictions#

    Optionally, an API key can be associated with a set of CIDR blocks, and only connections originating from IPs that are part of these CIDR blocks are allowed.
    A maximum of 64 IPs is allowed across the entire set of CIDR blocks.

    Rate Limiting#

    Rate limits are enforced system wide based on the originating client IP. A 429 HTTP Response is sent if the rate limit is exceeded.
    These 3 response headers are available on all the API endpoints, regardless of success or failure. These headers allow client applications to throttle their requests and obtain the best throughput within the enforced rate limits:
    x-ratelimit-limit - The maximum number of requests that a client can make within a 30 seconds window
    x-ratelimit-remaining - The number of requests remaining in the current rate limit window
    x-ratelimit-reset - The time at which the current rate limit window resets, in UTC epoch seconds
    Rate limits can be increased on a per Tenant / API Key basis, to a value above the system-wide limit. In this case, the client IP restriction becomes mandatory.

    Request Tracing#

    All endpoints support an optional HTTP header:
    x-request-id - A v4 uuid that allows tracing across multiple API services
    If a request id is not provided in this header, a value is auto-generated by the system.
    The response headers for all endpoints include the value of the provided or system generated x-request-id.
    For failed requests, all error messages JSON response payloads also include the same value in the requestId field. The value in this field has the dashes removed: a dashes-free value is more search-ready in various logging systems; otherwise some logging systems split the value into multiple tokens before storing it into their search indexes, making it hearder to find log records that match the request id value.
    Modified at 2025-12-07 12:33:40
    Previous
    Getting Started
    Next
    Terminology
    Built with