List transfers

GET/v1/payments/transfersRun in dashboard

Set custodyWalletId to select one exact SDP wallet; observed address history is opt-in with includeObserved=true.

Requires an API key with the transfers.read action.

Query parametersCopy Anchor Link

• custodyWalletId · string · min length 1 · example cwlt_example

  Filter persisted transfers by exact SDP Wallet ID.

• search · string · max length 200 · example xfr_example

  Search transfer ID, signature, provider reference, source or destination address, memo, counterparty ID, or counterparty display name. Use at least 3 non-whitespace characters; a blank value is treated as no search filter.

• token · string · example USDC

  Filter by token symbol or mint.

• direction · string · one of inbound, outbound · example outbound

  Filter by transfer direction.

• status · string · example completed,confirmed,finalized

  Filter by transfer status. Accepts a comma-separated list of statuses.

• category · string · always wallet

  Filter by wallet transfers or ramp transfers.

• type · string · example transfer,transfer_batch

  Filter by one or more comma-separated transfer types.

• counterpartyId · string · min length 1 · example cpty_example

  Filter transfers tied to a specific counterparty.

• providerReference · string · min length 1 · example Quote:019e979c-f660-5246-0000-c0588496b9ce

  Provider quote or transaction reference. Must be supplied with provider for exact ramp transfer lookup.

• from · string · format date-time · example 2025-01-01T00:00:00.000Z

  Filter from timestamp.

• to · string · format date-time · example 2025-01-02T00:00:00.000Z

  Filter to timestamp.

• includeObserved · string · one of true, false · default false · example false

  When custodyWalletId is supplied, also include RPC-observed activity for that exact wallet row's address. Observed rows have custodyWalletId null.

• sortBy · string · one of createdAt, updatedAt, amount, status · default createdAt · example createdAt

  Field used to sort the transfer list.

• sortDirection · string · one of asc, desc · default desc · example desc

  Sort direction.

• page · integer · greater than 0 · default 1 · example 1

  Page number (1-based).

• pageSize · integer · min 1 · max 100 · default 20 · example 20

  Items per page.

HeadersCopy Anchor Link

• x-project-id · string · min length 1 · example prj_example

  Required for dashboard sessions. API keys use their assigned project.

ResponsesCopy Anchor Link

• 200 Transfer list

  • data · object[] · required

    • fireblocks · object

      Native Fireblocks transfer tracking. A processing payment may await approval in Fireblocks; network fees are paid by its source vault. A missing transaction ID means submission is still being reconciled. Do not create a replacement payment while its outcome is unknown.

      • transactionId · string | null · required

      • status · string · required

      • subStatus · string | null · required

    • id · string · required · min length 1 · example xfr_example

      Transfer identifier (SDP record ID, not the on-chain signature).

    • organizationId · string · required · min length 1 · example org_example

      Organization identifier.

    • custodyWalletId · string | null · required · example cwlt_example

      Exact SDP Wallet ID associated with the persisted transfer, or null for unresolved legacy and observed rows.

    • providerWalletId · string · required · min length 1 · example privy_wallet_123

      Provider wallet ID retained as evidence; not an execution selector.

    • projectId · string · min length 1 · example prj_example

      Project identifier for the transfer.

    • type · string · required · example transfer

      Transfer type.

    • kind · string · required

      Dashboard transaction kind derived from the transfer type and originating Payments resource.

    • direction · string · required · one of inbound, outbound · example outbound

      Transfer direction.

    • status · string · required · one of pending, processing, confirmed, finalized, failed, awaiting_payment, settling, completed, canceled, expired · example confirmed

      Transfer status.

    • signature · string | null · required · example sig_example

      Solana transaction signature (tx id/hash).

    • serializedTx · string | null · required · min length 1 · example base64_tx_example

      Base64-encoded transaction payload, if available. Always null for transfer batch chunks, whose signed bytes stay server-side.

    • slot · integer | null · required · example 123456

      Slot number, if confirmed.

    • blockTime · string | null · required · format date-time · example 2025-01-01T00:00:00.000Z

      Block time, if confirmed.

    • confirmedAt · string · format date-time · example 2025-01-01T00:00:00.000Z

      When SDP confirmed the transfer. A ramp is confirmed once its delivery is verified onchain.

    • fee · integer | null · required · example 5000

      Transaction fee in lamports.

    • error · string | null · required · example Signature failed

      Error message if the transaction failed.

    • initiatedBy · object

      Initiator that triggered the transfer.

      • type · string · required · one of api_key, user, system · example api_key

        Initiator type.

      • id · string

        Initiator identifier if applicable.

      • display · string

        Human-friendly label for the initiator.

    • source · string · min length 32 · max length 44 · example So11111111111111111111111111111111111111112

      Source wallet address.

    • destination · string · min length 32 · max length 44 · example So11111111111111111111111111111111111111112

      Destination wallet address.

    • memo · string · max length 256

      Optional memo for the transfer.

    • rampsMemo · object · required

      Free-form key-value memo for offchain reconciliation of ramp transfers. At most 20 entries.

      • * · string · min length 1 · max length 256

    • token · string

      Token symbol or mint address.

    • amount · string · example 100.00

      Token amount in UI units (decimal string).

    • counterpartyId · string · example cpty_example

      Counterparty tied to the transfer record, when available.

    • counterpartyDisplayName · string · example Acme Studio

      Current display name of the counterparty tied to the transfer.

    • providerReference · string · example ramp_quote_example

      Provider quote or transaction reference used for ramp correlation.

    • deliveryMode · string · one of hosted, manual_instructions, session_widget · example session_widget

      Ramp delivery mode. Hosted flows require the customer to complete a provider-hosted UI; manual instructions require the customer to fund displayed instructions; session widgets use a provider SDK session.

    • fiatCurrency · string · example USD

      Fiat currency for the ramp leg.

    • fiatAmount · string · example 100.00

      Quoted fiat amount for the ramp leg: what the customer pays on an on-ramp, the payout quoted on an off-ramp. It never changes after the quote; an off-ramp's final payout is fiatPayout.

    • fiatPayout · object

      What the provider reports paying out once it settles an off-ramp sale. Provider-reported: SDP cannot verify a bank payout.

      • amount · string · required · example 20.82

        Fiat paid out, in display units. Differs from the quoted fiatAmount when the provider re-prices the sale at receipt.

      • currency · string · required · example USD

        ISO currency of the payout, as the provider reports it.

      • reportedAt · string · format date-time · example 2025-01-02T00:00:00.000Z

        When the provider reported the payout.

    • deliveryMismatch · object

      Present while SDP holds a provider-settled ramp in settling because the chain contradicts the provider's delivery. A new provider report clears it.

      • reason · string · required · one of provider_report_mismatch, transaction_failed, predates_transfer, not_delivered, amount_mismatch, transaction_not_found · example amount_mismatch

        Why the chain contradicts the provider: provider_report_mismatch (its report contradicts SDP's record), transaction_failed, predates_transfer (the transaction landed before the transfer), not_delivered (nothing of the quoted asset reached the quoted wallet), amount_mismatch, or transaction_not_found (no finalized transaction an hour after the report; SDP keeps checking, and a later delivery completes the transfer).

      • checkedAt · string · required · format date-time · example 2025-01-02T00:00:00.000Z

        When SDP's delivery check reached this verdict.

      • reportedAmount · string · example 20

        What the provider reported delivering, in display units.

      • observedAmount · string · example 0.5

        What the chain shows the quoted wallet received, in display units.

    • risk · object

      Optional risk evaluation for the transfer.

      • provider · string · required · example trm

        Risk scoring provider.

      • score · string · required · example 0.12

        Provider-specific risk score.

      • level · string · required · one of low, medium, high, unknown · example low

        Risk level classification.

      • evaluatedAt · string · required · format date-time · example 2025-01-01T00:00:00.000Z

        Timestamp when risk was evaluated.

    • createdAt · string · required · format date-time · example 2025-01-01T00:00:00.000Z

      Creation timestamp.

    • updatedAt · string · required · format date-time · example 2025-01-02T00:00:00.000Z

      Last update timestamp.

  • meta · object · required

    Pagination metadata.

    • total · integer · required · min 0

      Total items.

    • page · integer · required · greater than 0

      Current page number.

    • pageSize · integer · required · greater than 0

      Items per page.

    • hasMore · boolean · required

      Whether more pages exist.

    • requestId · string · required · min length 1 · example req_example

      Request identifier for tracing.

• 400 Bad Request

  • error · object · required

    Standard error payload.

    • code · string · required

      Machine-readable error code.

    • message · string · required

      Human-readable error message.

    • details · object

      Optional error details for debugging.

      • * · any

  • meta · object

    • requestId · string · min length 1 · example req_example

      Request identifier for tracing.

• 401 Unauthorized

  Same fields as 400.

• 403 Forbidden. Requires the transfers.read action: an API key must hold it (a module's manage or execute also covers its read), and a signed-in member's organization role must include it. Without it the error is INSUFFICIENT_PERMISSIONS and error.details.action names the action. Any other 403 names its own reason.

  Same fields as 400.

• 404 Not Found

  Same fields as 400.

• 409 Conflict

  Same fields as 400.

• 500 Internal Server Error

  Same fields as 400.