JupiterPerpsService can currently read Jupiter Perps positions and derive information such as entry price, collateral, fees, direction, traded asset, and liquidation price.
To support automated trading, the API must also be able to construct Solana transactions that modify Jupiter Perps positions.
The first required transaction-building operation is increasing a position.
The same Jupiter operation can be used in two situations:
If no matching position currently exists, a new position is opened.
If a matching position already exists for the same wallet, traded asset, and direction, the existing position is increased.
This issue only covers construction of the unsigned transaction.
Constructing an unsigned transaction does not change blockchain state. The state changes only after a wallet signs the transaction and submits it to the Solana blockchain. Therefore, this functionality remains read-only with respect to blockchain state.
Goal
Extend:
com.r35157.libs.jupiter.perps.JupiterPerpsService
with a method named:
buildPositionIncreaseTransaction(...)
The method must construct a complete unsigned Solana transaction which, after signing and submission, opens or increases a Jupiter Perps position.
The method should receive the information required by Jupiter, including:
The final parameters and ValueTag types should be decided during implementation based on the requirements of the Jupiter Perps API.
The API should preferably expose the position-size increase explicitly rather than only exposing leverage. Leverage can be calculated by the caller when appropriate.
Requirements
The method must be part of JupiterPerpsService.
The implementation must be added to the corresponding reference implementation.
The method must support both opening a new position and increasing an existing matching position.
The method must not access or receive any private key.
The method must not sign the transaction.
The method must not submit the transaction to Solana.
The method must construct or retrieve the complete unsigned Solana transaction required by Jupiter.
All required Jupiter and Solana instructions and accounts must be included.
Amounts, addresses, and other semantically distinct values must use appropriate ValueTag types.
The resulting transaction must be transferable to an external wallet or signer.
Existing read functionality in JupiterPerpsService must remain unaffected.
The complete repository must continue to compile.
Transaction result type
The transaction should not be returned as an unqualified String.
Introduce or reuse a domain type such as:
SolanaUnsignedTransaction
Depending on the Jupiter response and the final design, this type may contain:
The serialized unsigned transaction
The recent blockhash
The last valid block height
Any other information required by the signer or submitter
The exact representation should fit into the existing Solana architecture.
Initial supported use case
The initial implementation must support increasing an existing position by supplying additional USDC collateral and increasing the position size.
This can also be used as a practical way of adding collateral while reducing effective leverage.
For example, increasing a position using the minimum supported leverage, currently expected to be approximately 1.1, should primarily increase collateral while only increasing the position size by a relatively small amount.
Support for a pure collateral-only operation is not required for this issue.
Possible collateral-only operation
There is reason to suspect that Jupiter may support increasing collateral without increasing the position size.
The Jupiter increase-position request appears to distinguish between:
inputTokenAmount
and:
sizeUsdDelta
It may therefore be possible to construct a collateral-only transaction using:
inputTokenAmount > 0
sizeUsdDelta = 0
This behaviour is currently considered undocumented and must not be relied upon as part of the definition of done for this issue.
During implementation, it is acceptable to perform an early experiment to determine whether Jupiter accepts sizeUsdDelta = 0.
If this works, a later convenience method may be introduced, for example:
addPositionCollateral(...)
This method would not require a separate Jupiter transaction implementation. It could delegate to:
buildPositionIncreaseTransaction(...)
using:
inputTokenAmount > 0
sizeUsdDelta = 0
The collateral-only convenience method is outside the scope of this issue.
Verification
The implementation should support the following manual verification flow:
Read the current state of an existing Jupiter Perps position.
Construct an unsigned position-increase transaction.
Sign and submit the transaction using an external wallet or tool.
Read the position again.
Verify that the collateral and position size increased as expected.
The same method should also be capable of constructing a transaction that opens a new position when no matching position exists.
External signing and submission do not need to be implemented as part of this issue.
Out of scope
The following are not part of this issue:
Private-key handling or storage
Transaction signing
Submission of the transaction to Solana RPC
Solana CLI integration
An automated wallet service
Automatic decisions about when a position should be increased
Integration with Evelyn’s trading logic
Decreasing or closing positions
Withdrawing collateral
Guaranteed support for collateral-only deposits
A general-purpose wallet implementation
These areas can be handled in subsequent issues.
Definition of done
JupiterPerpsService contains a buildPositionIncreaseTransaction(...) method.
The reference implementation can construct an unsigned transaction for opening or increasing a Jupiter Perps position.
The transaction contains all required instructions and accounts.
The transaction contains no signature and requires no private key to construct.
The transaction can be transferred to an external signer.
After external signing and submission, the transaction opens or increases the expected position.
Increasing an existing position updates its collateral and position size as expected.
The implementation has been tested against at least one Jupiter Perps position.
The complete repository compiles.
## Background
`JupiterPerpsService` can currently read Jupiter Perps positions and derive information such as entry price, collateral, fees, direction, traded asset, and liquidation price.
To support automated trading, the API must also be able to construct Solana transactions that modify Jupiter Perps positions.
The first required transaction-building operation is increasing a position.
The same Jupiter operation can be used in two situations:
* If no matching position currently exists, a new position is opened.
* If a matching position already exists for the same wallet, traded asset, and direction, the existing position is increased.
This issue only covers construction of the unsigned transaction.
Constructing an unsigned transaction does not change blockchain state. The state changes only after a wallet signs the transaction and submits it to the Solana blockchain. Therefore, this functionality remains read-only with respect to blockchain state.
## Goal
Extend:
```java
com.r35157.libs.jupiter.perps.JupiterPerpsService
```
with a method named:
```java
buildPositionIncreaseTransaction(...)
```
The method must construct a complete unsigned Solana transaction which, after signing and submission, opens or increases a Jupiter Perps position.
The method should receive the information required by Jupiter, including:
* The wallet that owns the position
* The traded asset
* The position direction
* The input collateral token
* The input token amount
* The requested position size increase
* Any required slippage configuration
Possible API direction:
```java
SolanaUnsignedTransaction buildPositionIncreaseTransaction(
ΩSolanaWalletIdΩ wallet,
ΩSPLMintAddressΩ tradedTokenMint,
JupiterPerpsPositionDirection direction,
ΩSPLMintAddressΩ inputTokenMint,
ΩUSDCAmountΩ inputTokenAmount,
ΩUSDCAmountΩ sizeUsdDelta);
```
The final parameters and ValueTag types should be decided during implementation based on the requirements of the Jupiter Perps API.
The API should preferably expose the position-size increase explicitly rather than only exposing leverage. Leverage can be calculated by the caller when appropriate.
## Requirements
* The method must be part of `JupiterPerpsService`.
* The implementation must be added to the corresponding reference implementation.
* The method must support both opening a new position and increasing an existing matching position.
* The method must not access or receive any private key.
* The method must not sign the transaction.
* The method must not submit the transaction to Solana.
* The method must construct or retrieve the complete unsigned Solana transaction required by Jupiter.
* All required Jupiter and Solana instructions and accounts must be included.
* Amounts, addresses, and other semantically distinct values must use appropriate ValueTag types.
* The resulting transaction must be transferable to an external wallet or signer.
* Existing read functionality in `JupiterPerpsService` must remain unaffected.
* The complete repository must continue to compile.
## Transaction result type
The transaction should not be returned as an unqualified `String`.
Introduce or reuse a domain type such as:
```java
SolanaUnsignedTransaction
```
Depending on the Jupiter response and the final design, this type may contain:
* The serialized unsigned transaction
* The recent blockhash
* The last valid block height
* Any other information required by the signer or submitter
The exact representation should fit into the existing Solana architecture.
## Initial supported use case
The initial implementation must support increasing an existing position by supplying additional USDC collateral and increasing the position size.
This can also be used as a practical way of adding collateral while reducing effective leverage.
For example, increasing a position using the minimum supported leverage, currently expected to be approximately `1.1`, should primarily increase collateral while only increasing the position size by a relatively small amount.
Support for a pure collateral-only operation is not required for this issue.
## Possible collateral-only operation
There is reason to suspect that Jupiter may support increasing collateral without increasing the position size.
The Jupiter increase-position request appears to distinguish between:
```text
inputTokenAmount
```
and:
```text
sizeUsdDelta
```
It may therefore be possible to construct a collateral-only transaction using:
```text
inputTokenAmount > 0
sizeUsdDelta = 0
```
This behaviour is currently considered undocumented and must not be relied upon as part of the definition of done for this issue.
During implementation, it is acceptable to perform an early experiment to determine whether Jupiter accepts `sizeUsdDelta = 0`.
If this works, a later convenience method may be introduced, for example:
```java
addPositionCollateral(...)
```
This method would not require a separate Jupiter transaction implementation. It could delegate to:
```java
buildPositionIncreaseTransaction(...)
```
using:
```text
inputTokenAmount > 0
sizeUsdDelta = 0
```
The collateral-only convenience method is outside the scope of this issue.
## Verification
The implementation should support the following manual verification flow:
1. Read the current state of an existing Jupiter Perps position.
2. Construct an unsigned position-increase transaction.
3. Sign and submit the transaction using an external wallet or tool.
4. Read the position again.
5. Verify that the collateral and position size increased as expected.
The same method should also be capable of constructing a transaction that opens a new position when no matching position exists.
External signing and submission do not need to be implemented as part of this issue.
## Out of scope
The following are not part of this issue:
* Private-key handling or storage
* Transaction signing
* Submission of the transaction to Solana RPC
* Solana CLI integration
* An automated wallet service
* Automatic decisions about when a position should be increased
* Integration with Evelyn’s trading logic
* Decreasing or closing positions
* Withdrawing collateral
* Guaranteed support for collateral-only deposits
* A general-purpose wallet implementation
These areas can be handled in subsequent issues.
## Definition of done
* `JupiterPerpsService` contains a `buildPositionIncreaseTransaction(...)` method.
* The reference implementation can construct an unsigned transaction for opening or increasing a Jupiter Perps position.
* The transaction contains all required instructions and accounts.
* The transaction contains no signature and requires no private key to construct.
* The transaction can be transferred to an external signer.
* After external signing and submission, the transaction opens or increases the expected position.
* Increasing an existing position updates its collateral and position size as expected.
* The implementation has been tested against at least one Jupiter Perps position.
* The complete repository compiles.
minimons
self-assigned this 2026-07-16 19:09:36 +02:00
minimons
added this to the AssetAZ project 2026-07-16 19:09:36 +02:00
minimons
changed title from Generate an unsigned transaction for adding collateral to a Jupiter Perps position to Generate an unsigned transaction for increasing a Jupiter Perps position2026-07-16 20:49:22 +02:00
minimons
moved this to In Progress in AssetAZ on 2026-07-17 19:31:39 +02:00
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Background
JupiterPerpsServicecan currently read Jupiter Perps positions and derive information such as entry price, collateral, fees, direction, traded asset, and liquidation price.To support automated trading, the API must also be able to construct Solana transactions that modify Jupiter Perps positions.
The first required transaction-building operation is increasing a position.
The same Jupiter operation can be used in two situations:
This issue only covers construction of the unsigned transaction.
Constructing an unsigned transaction does not change blockchain state. The state changes only after a wallet signs the transaction and submits it to the Solana blockchain. Therefore, this functionality remains read-only with respect to blockchain state.
Goal
Extend:
with a method named:
The method must construct a complete unsigned Solana transaction which, after signing and submission, opens or increases a Jupiter Perps position.
The method should receive the information required by Jupiter, including:
Possible API direction:
The final parameters and ValueTag types should be decided during implementation based on the requirements of the Jupiter Perps API.
The API should preferably expose the position-size increase explicitly rather than only exposing leverage. Leverage can be calculated by the caller when appropriate.
Requirements
JupiterPerpsService.JupiterPerpsServicemust remain unaffected.Transaction result type
The transaction should not be returned as an unqualified
String.Introduce or reuse a domain type such as:
Depending on the Jupiter response and the final design, this type may contain:
The exact representation should fit into the existing Solana architecture.
Initial supported use case
The initial implementation must support increasing an existing position by supplying additional USDC collateral and increasing the position size.
This can also be used as a practical way of adding collateral while reducing effective leverage.
For example, increasing a position using the minimum supported leverage, currently expected to be approximately
1.1, should primarily increase collateral while only increasing the position size by a relatively small amount.Support for a pure collateral-only operation is not required for this issue.
Possible collateral-only operation
There is reason to suspect that Jupiter may support increasing collateral without increasing the position size.
The Jupiter increase-position request appears to distinguish between:
and:
It may therefore be possible to construct a collateral-only transaction using:
This behaviour is currently considered undocumented and must not be relied upon as part of the definition of done for this issue.
During implementation, it is acceptable to perform an early experiment to determine whether Jupiter accepts
sizeUsdDelta = 0.If this works, a later convenience method may be introduced, for example:
This method would not require a separate Jupiter transaction implementation. It could delegate to:
using:
The collateral-only convenience method is outside the scope of this issue.
Verification
The implementation should support the following manual verification flow:
The same method should also be capable of constructing a transaction that opens a new position when no matching position exists.
External signing and submission do not need to be implemented as part of this issue.
Out of scope
The following are not part of this issue:
These areas can be handled in subsequent issues.
Definition of done
JupiterPerpsServicecontains abuildPositionIncreaseTransaction(...)method.Generate an unsigned transaction for adding collateral to a Jupiter Perps positionto Generate an unsigned transaction for increasing a Jupiter Perps position