$PRIVY is live -

Skip to content
Docs

API reference

Trade status

Look up and poll a buy or sell.

Use the full trade for display and the compact status for polling. Both are read-only: looking up a trade never advances or retries it.

Get a trade

GET/api/v1/trades/{id}API key

Looks up a buy by its UUID or a sell by its group key. Read-only: this never advances or retries a trade.

Parameters

  • idstring · pathrequired

    Buy UUID or sell group key.

Response

  • idstring

    Trade ID. A UUID for buys, a group key for sells.

  • sidestring

    Trade direction.

    buysell

  • statusstring

    Raw internal status. Prefer stage for display.

  • stagestring

    Normalised lifecycle stage.

    awaiting_depositconfirming_depositfundingexecutingsettlingcompletedfailedrefundingrefundedexpiredcancelledrequires_review

  • terminalboolean

    True once the trade will not change again.

  • inputMintstring

    Mint spent.

  • outputMintstring

    Mint received.

  • inputAmountstring

    Raw input amount (lamports for buys).

  • expectedOutputAmountstring

    Quoted raw output amount.

  • minimumOutputAmountstring

    Minimum output locked by slippage tolerance.

  • receivedOutputAmountstringnullable

    Raw output actually received.

  • slippageBpsintegernullable

    Slippage tolerance in basis points.

  • platformFeeLamportsstringnullable

    Platform fee charged on a buy.

  • signaturesobject

    On-chain transaction signatures.

    • depositstringnullable

      Deposit transaction signature (buys).

    • swapsstring[]

      Swap transaction signatures.

    • payoutsstring[]

      SOL payout signatures (sells).

    • refundstringnullable

      Refund signature when a buy was refunded.

  • refundobjectnullable

    Refund progress when a buy could not execute.

    • statestring

      Refund state.

      recoveringin_progresscomplete

    • amountLamportsstringnullable

      Refunded lamports.

  • failureobjectnullable

    Failure details when the trade failed.

    • codestringnullable

      Machine-readable failure code.

    • reasonstringnullable

      Human-readable reason.

  • createdAtstring · date-time

    When the trade was created.

  • expiresAtstring · date-timenullable

    Deposit deadline for buys.

  • completedAtstring · date-timenullable

    When the trade completed.

curl "https://privy.ac/api/v1/trades/9c1d2e3f-4a5b-4c6d-8e7f-0123456789ab" \
  -H "X-API-Key: $PRIVY_API_KEY"

Try it

Sends a real request
Example response
{
  "data": {
    "id": "9c1d2e3f-4a5b-4c6d-8e7f-0123456789ab",
    "side": "buy",
    "status": "completed",
    "stage": "completed",
    "terminal": true,
    "inputMint": "So11111111111111111111111111111111111111112",
    "outputMint": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
    "inputAmount": "50000000",
    "expectedOutputAmount": "162010220",
    "minimumOutputAmount": "137708687",
    "receivedOutputAmount": "161834512",
    "slippageBps": 1500,
    "platformFeeLamports": "500000",
    "signatures": {
      "deposit": "3uYp...9Fa",
      "swaps": [
        "5h8Xb3...kQ2"
      ],
      "payouts": [],
      "refund": null
    },
    "refund": null,
    "failure": null,
    "createdAt": "2026-10-09T18:21:58.000Z",
    "expiresAt": "2026-10-09T18:31:58.000Z",
    "completedAt": "2026-10-09T18:22:41.000Z"
  },
  "requestId": "req_8f3a2c91d4e6b07f"
}

Get trade status

GET/api/v1/trades/{id}/statusAPI key

A smaller payload for polling until terminal is true. Poll no faster than every 2 seconds.

Parameters

  • idstring · pathrequired

    Buy UUID or sell group key.

Response

  • idstring

    Trade ID. A UUID for buys, a group key for sells.

  • sidestring

    Trade direction.

    buysell

  • statusstring

    Raw internal status. Prefer stage for display.

  • stagestring

    Normalised lifecycle stage.

    awaiting_depositconfirming_depositfundingexecutingsettlingcompletedfailedrefundingrefundedexpiredcancelledrequires_review

  • terminalboolean

    True once the trade will not change again.

  • signaturesobject

    On-chain transaction signatures.

    • depositstringnullable

      Deposit transaction signature (buys).

    • swapsstring[]

      Swap transaction signatures.

    • payoutsstring[]

      SOL payout signatures (sells).

    • refundstringnullable

      Refund signature when a buy was refunded.

  • failureobjectnullable

    Failure details when the trade failed.

    • codestringnullable

      Machine-readable failure code.

    • reasonstringnullable

      Human-readable reason.

  • refundobjectnullable

    Refund progress when a buy could not execute.

    • statestring

      Refund state.

      recoveringin_progresscomplete

    • amountLamportsstringnullable

      Refunded lamports.

  • completedAtstring · date-timenullable

    When the trade completed.

curl "https://privy.ac/api/v1/trades/9c1d2e3f-4a5b-4c6d-8e7f-0123456789ab/status" \
  -H "X-API-Key: $PRIVY_API_KEY"

Try it

Sends a real request
Example response
{
  "data": {
    "id": "9c1d2e3f-4a5b-4c6d-8e7f-0123456789ab",
    "side": "buy",
    "status": "swap_submitted",
    "stage": "executing",
    "terminal": false,
    "signatures": {
      "deposit": "3uYp...9Fa",
      "swaps": [
        "5h8Xb3...kQ2"
      ],
      "payouts": [],
      "refund": null
    },
    "failure": null,
    "refund": null,
    "completedAt": null
  },
  "requestId": "req_8f3a2c91d4e6b07f"
}