Initialize Position

It creates a position offchain and onchain (optional). Use the itemData.alreadyOnchain=true setting to only onboard the position into Vulcan Forge but not submit a Solana transaction to create the position/token account on the network (because the token account would already be on the network).

If the owner Account on this position has a tokenDebitApiKeys set the API Key Identifier performing the intiailize operation, needs to be part of the list setup in the owner account tokenDebitApiKeys, in order to be able to set the override of the tokenDebitApiKeys at the position level.

If the owner Account on this position is off platform, the position will also be created off platform only (i.e. only onchain and not within the Vulcan Forge offchain DB). As such the alreadyOnchain=true is not allowed under this condition.

Default Debit Limits:
Unless overriden through configurations on the tokenDebitLimits field, the defaults reflected in the tables below apply.

These defaults are put in place to reduce the chances of accidental debit operations and to increase the chances of having some escape routes to clawback funds/tokens sent to unwanted destinations when accidents do happen. Use caution when increasing these limits and be as specific as possible to the scope that they should apply to - e.g. don't increase the limits on Burn operations too if you want to only increase the limits for outgoing transfers.

If the tokenDebitLimits field is provided, all the defaults specified below will not be applied any longer, regardless of what entries this array has. Only the debit limits provided in the field will be enforced.

OUTGOING TRANSFERS

Destination	Limit Type	Max allowed amount w/o approval
OFF_PLATFORM	PER_TRANSACTIONN	0
OFF_PLATFORM	DURATION (last 24hrs)	0
NON_MANAGED	PER_TRANSACTION	10
NON_MANAGED	DURATION (last 24hrs)	Unlimited
MANAGED	PER_TRANSACTION	Unlimited
MANAGED	DURATION (last 24hrs)	Unlimited

BURNS

Mint Authority	Limit Type	Max allowed amount w/o approval
NON_MANAGED	PER_TRANSACTION	0
NON_MANAGED	DURATION (last 24hrs)	0
MANAGED	PER_TRANSACTION	Unlimited
MANAGED	DURATION (last 24hrs)	Unlimited

Account Types (for the OUTGOING TRANSFER Destination and Mint Authority for the token being BURNed):

OFF_PLATFORM - Not onboarded on the Vulcan Forge platform

NON_MANAGED - Onboarded on the platform, but private key not hosted on it

MANAGED - Onboarded on the platform and private key hosted on it

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

curl --location --request POST 'https://vf-solana-api.dev.alphaledger.com/api/v1/positions?svmCluster=SOLANA_DEVNET' \ --header 'x-request-id: f9860f73-a466-41f2-a083-34eeb1cc3a3c' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "itemData": { "owner": { "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 }, "financialInstrument": { "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 }, "alreadyOnchain": false, "tokenDebitApiKeys": [ "string" ], "tokenDebitLimits": [ { "operationType": "ANY", "destination": "ANY", "mintAuthority": "ANY", "maxAllowedDebit": { "limitType": "PER_TRANSACTION", "limitAmount": 100, "duration": { "code": "DAYS", "unit": 1 }, "approversForOverride": [ "string" ], "requiredApproversCount": 3 } } ], "unfreezeIfNeeded": false, "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 }, "seed": { "amount": 3.8097, "lamports": 8733302 }, "freezeAfterSeed": 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 }, "requireMemoOnTransfer": false }, "svmTransactionConfig": { "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": 0, "price": 0, "priceEstimate": { "provider": "HELIUS", "calculationStrategy": "DEFAULT", "priorityLevel": "RECOMMENDED" } }, "commitmentConfig": { "commitmentLevel": "processed" }, "messageLifetimeStrategy": "RECENT_BLOCKHASH", "transactionVersion": "V0" }, "tenancyConfig": { "overrideOrganizationExternalId": "ALIM" } }'

{ "newPosition": { "onchainId": "ndA7eTfoWqrczXYUq53gNRRjQgEmufqErXbgXUFFUAA", "offchainId": "1a1e904d-0d95-4e66-85e1-88a57774e910" }, "svmTransaction": { "success": false, "offchainId": "ee36c656-aa74-4d6a-b23c-332c204cb202", "status": "SIGNED", "onchainId": "5nwo7XvhiVRpJasEzH5r3hGKJqaTxd7qVit3cedFJgESdAPrmawebMJu6fUKRfjXEaivuey7vBsW56xPxX76T1bm", "confirmationsCount": 2, "serializedMessage": "string", "errorMessage": "string", "txnTimestamp": "2025-10-21T16:17:45.035372Z" } }

Request

Responses