The Trigger Order V2 API is in beta and under active development. Behaviour, endpoints, and response formats may change as we iterate based on integrator feedback. Pin to specific response schemas and handle unknown fields gracefully.
Reference Implementation
The jup.ag frontend is the canonical reference for how to interact with the V2 API. When in doubt about edge cases, validation logic, or UX patterns, refer to how jup.ag handles it. This includes:
- Order creation flows and parameter validation
- Price and slippage presentation
- Error handling and retry logic
- Order state management and polling
Order Expiry
Every order requires an expiresAt timestamp. Unlike V1 where orders could exist indefinitely, V2 enforces expiry on all orders. This allows the system to prune stale orders, improving execution quality for active orders.
| Use case | Recommended expiry |
|---|
| Short-term trades | 1-7 days |
| Swing trades | 7-30 days |
| Long-duration positions | 30 days, with periodic renewal |
Slippage
| Order type | Default | Recommendation |
|---|
| Take-profit / buy below | Auto (RTSE) | Use the default unless you have specific requirements |
| Stop-loss / buy above | 20% (2000 bps) | Keep high for execution certainty — tighten only if you accept missed fills |
| Parent (OTOCO) | Auto (RTSE) | Use the default |
Error Handling
- Validation errors (400) include a
details object with per-field messages. Parse these to surface specific issues to users.
- Authentication errors (401) mean the JWT has expired. Re-authenticate with a new challenge-response flow rather than retrying the same token.
- Minimum order size is 10 USD. Enforce this client-side to avoid unnecessary API calls.
- Handle unknown fields in responses gracefully. As the API evolves during beta, new fields may be added to response objects.
Order Summary
The API does not validate whether your trigger price makes economic sense. If a user sets a buy order above market price or a sell order below market price, the keeper will execute as instructed and the difference is lost.
Display a human-readable summary of what the order will do before the user confirms. On jup.ag, the confirmation shows a plain-language description like:
Buy SOL with 15 USDC when price goes below 76.37(−1084.01.
This helps users catch mistakes before submitting. For OCO and OTOCO orders, include both the trigger conditions and the child order parameters in the summary.
Token Compatibility
- Tokens with transfer tax extensions (Token-2022) are not supported
- Input and output mints must be different
Order Lifecycle
Poll the history endpoint to track order state. Key states to handle:
| State | Meaning | Action |
|---|
open | Active, waiting for trigger | No action needed |
filled | Fully executed | Show completion to user |
cancelled | Cancelled by user | Confirm funds returned to vault |
expired | Past expiresAt | Prompt user to withdraw funds or recreate |
failed | Execution failed | Show error, suggest retry with adjusted parameters |
