Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.starkfi.io/llms.txt

Use this file to discover all available pages before exploring further.

After you build a deposit, withdraw, or rebalance operation and the user signs the wire (base64), you must submit the signed payload only through this endpoint. Do not call sendTransaction or public RPC broadcast yourself — StarkFi confirms the transaction and updates the tracked positions in one flow.

​
Endpoint

POST /yield/broadcast
1

Broadcast all operations

​
Request body (all operations)

ParameterTypeRequiredDescription
operationstring✅One of: deposit, withdraw, rebalance.
op_signedstring | string[]✅Base64 signed Solana transaction wire. Deposit and withdraw: exactly one string. Rebalance: one string (merged tx) or an array of two strings [withdraw, deposit] when the build returned two transactions.
position_idstringPosition UUID returned when building deposit or withdraw. *Required when operation is deposit or withdraw.
position_instringTarget position UUID for rebalance (deposit leg). **Required when operation is rebalance.
position_outstringSource position UUID for rebalance (withdraw leg). **Required when operation is rebalance.
position_id / position_in / position_out must belong to the same tenant as the authenticated session or integration x-api-key.
2

Broadcast deposit

Use the position_id from POST /api/yield/deposit.
curl --request POST \
  --url https://api.starkfi.io/yield/broadcast \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api_key>' \
  --data '{
    "operation": "deposit",
    "position_id": "<position_id_from_build>",
    "op_signed": "<base64_signed_transaction>"
  }'

​
Success response (status in body)

broadcast_deposit_yield_strategy_ok
{
  "statusCode": 200,
  "success": true,
  "status": "broadcast_deposit_yield_strategy_ok",
  "message": "Yield operation broadcasted and positions confirmed successfully",
  "data": {
    "status": 1,
    "transactionHash": "<solana_signature>",
    "position_in": {
      "position_id": "<uuid>",
      "strategy_name": "jupiter_lend",
      "strategy_symbol": "USDC",
      "wallet_manager": "<pubkey>",
      "deposit_position": 100.5,
      "last_move_amount": 100.5,
      "status": "confirmed_position"
    }
  }
}
3

Broadcast withdraw

Use the position_id from POST /api/yield/withdraw.
curl --request POST \
  --url https://api.starkfi.io/yield/broadcast \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api_key>' \
  --data '{
    "operation": "withdraw",
    "position_id": "<position_id_from_build>",
    "op_signed": "<base64_signed_transaction>"
  }'

​
Success response (status in body)

broadcast_withdraw_yield_strategy_ok
{
  "statusCode": 200,
  "success": true,
  "status": "broadcast_withdraw_yield_strategy_ok",
  "message": "Yield operation broadcasted and positions confirmed successfully",
  "data": {
    "status": 1,
    "transactionHash": "<solana_signature>",
    "position_out": {
      "position_id": "<uuid>",
      "strategy_name": "jupiter_lend",
      "strategy_symbol": "USDC",
      "wallet_manager": "<pubkey>",
      "deposit_position": 0,
      "last_move_amount": 50,
      "status": "confirmed_position"
    }
  }
}
4

Broadcast rebalance

Use position_out_id and position_in_id from PATCH /api/yield/rebalance.
curl --request POST \
  --url https://api.starkfi.io/yield/broadcast \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api_key>' \
  --data '{
    "operation": "rebalance",
    "position_out": "<position_out_id>",
    "position_in": "<position_in_id>",
    "op_signed": "<base64_signed_merged_tx>"
  }'

​
Success response (status in body)

broadcast_rebalance_yield_strategy_ok
{
  "statusCode": 200,
  "success": true,
  "status": "broadcast_rebalance_yield_strategy_ok",
  "message": "Yield operation broadcasted and positions confirmed successfully",
  "data": {
    "status": 1,
    "transactionHash": "<solana_signature_or_null>",
    "position_out": {
      "position_id": "<uuid>",
      "strategy_name": "kamino",
      "strategy_symbol": "USDC",
      "wallet_manager": "<pubkey>",
      "deposit_position": 0,
      "last_move_amount": 10,
      "status": "confirmed_position"
    },
    "position_in": {
      "position_id": "<uuid>",
      "strategy_name": "jupiter_lend",
      "strategy_symbol": "USDC",
      "wallet_manager": "<pubkey>",
      "deposit_position": 10,
      "last_move_amount": 10,
      "status": "confirmed_position"
    }
  }
}

​
Errors

HTTPTypicalstatus / messageWhen it occurs
400invalid_parametersZod validation (e.g. missing position_id, wrong op_signed count, missing position_in / position_out for rebalance).
400signed_transaction_missingNo usable signed payload after normalization.
400operation_not_supportedoperation not in deposit | withdraw | rebalance.
404deposit_position_not_foundposition_id missing or not owned by tenant (deposit).
404withdraw_position_not_foundSame for withdraw.
404rebalance_position_out_not_found / rebalance_position_in_not_foundInvalid or foreign position_out / position_in.
409solana_blockhash_expiredSigned wire no longer valid for current blockhash — rebuild the unsigned operation and sign again.
409yield_kind_operation_mismatchPosition status does not match the pending operation (e.g. stale rebalance). Server may refresh pending fields; rebuild the operation before broadcasting again.
504broadcast_confirmation_timeoutSubmitted but not confirmed within the internal timeout — check the signature on a Solana explorer before retrying.
502broadcast_* / confirm_*Broadcast or post-broadcast confirmation failed (see details in error body).
500server_errorUnhandled exception in the controller.
Partial rebalance failure (withdraw broadcasted, deposit failed) may return broadcast_rebalance_deposit_yield_strategy_failed with structured details (withdraw receipt + deposit error + position_out snapshot). Treat as a support / recovery path, not a silent retry without checking chain state.
Relation to StarkPay POST /payment/execute/on-chainThis /api/yield/broadcast endpoint is only for yield (lending) flows built via /api/yield/*. StarkPay card/PIX/crypto checkout continues to use /payment/... and payment_id — do not mix the two models.