transfer.v1.InternalTransferService

GetInternalTransfer

Read an accepted transfer by request ID or transfer ID, scoped to its source account. JWT session authentication only; API keys are not supported. Returns NotFound for unknown, pending, or inaccessible transfers. This read does not submit or retry a transfer and requires no fresh MFA.

Method

POST

Path

transfer.v1.InternalTransferService/GetInternalTransfer

Service

transfer.v1.InternalTransferService

Visibility

Authentication required

Authentication

Session token

MFA Requirement

Not required

POST

transfer.v1.InternalTransferService/GetInternalTransfer

Request

Testnet

curl --request POST \ \
  --url 'https://api.testnet.polyester.com/transfer.v1.InternalTransferService/GetInternalTransfer' \
  --header 'Content-Type: application/json' \
  --header 'Connect-Protocol-Version: 1' \
  --data '{
  "requestId": "request_01J0EXAMPLE",
  "subaccountId": "6789012345678"
}'

Responses

{
  "acceptedAtTsNs": "1735689600000000000",
  "flowId": "flow_7YWHMfk9JZeLMgZauHuiSxhJ",
  "requestId": "request_01J0EXAMPLE",
  "transferId": "9155001234569"
}

Request

transfer.v1.GetInternalTransferRequest

Response

transfer.v1.GetInternalTransferResponse

subaccountId string (fixed64)

Optional source public subaccount ID. Omitted means the authenticated root account. The caller must have access to the selected subaccount. Public ID. ConnectRPC carries it as fixed64 (a decimal string in JSON).

requestId string required one of 1-128 chars

Exact server-owned request ID returned by CreateInternalTransfer.

transferId string required one of 1-39 chars /^[1-9][0-9]*$/

Exact transfer ID returned by CreateInternalTransfer or ListTransfers.

one-of

requestId string

Stable server-owned intake request identifier.

transferId string

Stable transfer identifier shared by its debit and credit ledger entries.

flowId string

Authoritative lifecycle identifier for GetFlowById. The flow's ledger settlement step links back through milestone_tx_ref.

acceptedAtTsNs string (uint64)

Acceptance timestamp in nanoseconds since epoch (UTC).

Possible errors: 27

Key	HTTP status	Connect code	Error	When
account-shard-unavailable	503	unavailable	Account Shard Unavailable	The account shard cannot currently accept fund movement.
capital-view-unavailable	503	unavailable	Capital View Unavailable	The authoritative capital view is not ready.
conflict	409	aborted	Conflict	The request conflicts with existing state.
destination-inactive	400	failed_precondition	Destination Inactive	The destination account is not active.
destination-not-found	404	not_found	Destination Not Found	The destination account could not be found.
destination-not-whitelisted	403	permission_denied	Destination Not Whitelisted	The destination is not on the caller's internal whitelist.
failed-precondition	400	failed_precondition	Failed Precondition	A required transfer precondition was not satisfied.
funds-lock-conflict	409	aborted	Funds Lock Conflict	The funds lock conflicts with an existing or finalized reservation.
idempotency-conflict	409	already_exists	Idempotency Conflict	The idempotency key was reused with different request data.
insufficient-funds	400	failed_precondition	Insufficient Funds	The source account does not have enough available Trading balance.
internal-error	500	internal	Internal Error	The transfer failed because of an unexpected server error.
invalid-amount	400	invalid_argument	Invalid Amount	The transfer amount is invalid.
invalid-destination	400	invalid_argument	Invalid Destination	The destination identifier is invalid.
invalid-request	400	invalid_argument	Invalid Request	The request payload or one of its fields is invalid.
invalid-subaccount-id	400	invalid_argument	Invalid Subaccount	The selected subaccount identifier is invalid.
not-found	404	not_found	Not Found	The requested resource was not found.
permission-denied	403	permission_denied	Permission Denied	The caller is not permitted to create this transfer.
policy-denied	403	permission_denied	Policy Denied	An account or API-key policy rejected the transfer.
rate-limit-exceeded	429	resource_exhausted	Rate Limit Exceeded	The transfer admission rate limit was exceeded.
same-source-destination	400	invalid_argument	Source Equals Destination	Source and destination must be different accounts.
service-unavailable	503	unavailable	Service Unavailable	A required service is temporarily unavailable.
smart-account-unavailable	400	failed_precondition	Smart Account Unavailable	A required smart-account address is unavailable.
source-account-inactive	400	failed_precondition	Source Account Inactive	The source account is not active.
step-up-unavailable	503	unavailable	Step-Up Unavailable	Fresh step-up verification is temporarily unavailable.
subaccount-not-found	404	not_found	Subaccount Not Found	The selected subaccount does not exist.
unauthenticated	401	unauthenticated	Unauthenticated	Authentication is required.
unsupported-asset	400	invalid_argument	Unsupported Asset	The requested asset is not supported for internal transfers.