> Solana Developer Platform docs, served as Markdown. The [docs index](https://platform.solana.com/docs.md) lists every page and [llms.txt](https://platform.solana.com/docs/ai/llms.txt) the key ones; [SKILL.md](https://platform.solana.com/SKILL.md) has the rules for building on SDP. # List transfers Lists persisted payment transfers for the authenticated scope. `GET /v1/payments/transfers` Set custodyWalletId to select one exact SDP wallet; observed address history is opt-in with includeObserved=true. Requires an [API key](/docs/developing-with-sdp/authentication) with the `transfers.read` action. ## Query parameters - **`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. ## Headers - **`x-project-id`** · `string` · min length 1 · example `prj_example` Required for dashboard sessions. API keys use their assigned project. ## Responses - **`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`. ## Example request ```bash tab="cURL" curl 'https://api.solana.com/v1/payments/transfers' \ -H "Authorization: Bearer $SDP_API_KEY" ``` ```ts tab="TypeScript" const res = await fetch("https://api.solana.com/v1/payments/transfers", { method: "GET", headers: { Authorization: `Bearer ${process.env.SDP_API_KEY}` } }); ``` ```python tab="Python" import os, requests r = requests.get("https://api.solana.com/v1/payments/transfers", headers={"Authorization": f"Bearer {os.environ['SDP_API_KEY']}"}) ``` ## Example responses ```json tab="200" { "data": [ { "fireblocks": { "transactionId": "transaction_example", "status": "example", "subStatus": "example" }, "id": "xfr_example", "organizationId": "org_example", "custodyWalletId": "cwlt_example", "providerWalletId": "privy_wallet_123", "projectId": "prj_example", "type": "transfer", "kind": "example", "direction": "outbound", "status": "confirmed", "signature": "sig_example", "serializedTx": "base64_tx_example", "slot": 123456, "blockTime": "2025-01-01T00:00:00.000Z", "confirmedAt": "2025-01-01T00:00:00.000Z", "fee": 5000, "error": "Signature failed", "initiatedBy": { "type": "api_key" }, "source": "So11111111111111111111111111111111111111112", "destination": "So11111111111111111111111111111111111111112", "rampsMemo": { "invoice": "INV-123", "po": "PO-9" }, "amount": "100.00", "counterpartyId": "cpty_example", "counterpartyDisplayName": "Acme Studio", "providerReference": "ramp_quote_example", "deliveryMode": "session_widget", "fiatCurrency": "USD", "fiatAmount": "100.00", "fiatPayout": { "amount": "20.82", "currency": "USD", "reportedAt": "2025-01-02T00:00:00.000Z" }, "deliveryMismatch": { "reason": "amount_mismatch", "checkedAt": "2025-01-02T00:00:00.000Z", "reportedAmount": "20", "observedAmount": "0.5" }, "risk": { "provider": "trm", "score": "0.12", "level": "low", "evaluatedAt": "2025-01-01T00:00:00.000Z" }, "createdAt": "2025-01-01T00:00:00.000Z", "updatedAt": "2025-01-02T00:00:00.000Z" } ], "meta": { "total": 1, "page": 1, "pageSize": 1, "hasMore": false, "requestId": "req_example" } } ``` ```json tab="403" { "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "Missing action: transfers.read", "details": { "action": "transfers.read" } }, "meta": { "requestId": "req_example" } } ``` Error responses use the [standard error shape](/docs/reference/conventions/errors).