transfer.v1.InternalTransferService
CreateInternalTransfer
Create or return one accepted Trading to Trading transfer. Root-owner same-owner transfers and root-owner transfers to explicitly whitelisted destinations accept recent MFA; delegated and other interactive transfers require fresh step-up.
Request
curl --request POST \ \
--url 'https://api.testnet.polyester.com/transfer.v1.InternalTransferService/CreateInternalTransfer' \
--header 'Content-Type: application/json' \
--header 'Connect-Protocol-Version: 1' \
--data '{
"amountE18": {
"hi": "1",
"lo": "1"
},
"assetId": 100,
"destinationAccountId": "7563897446546",
"idempotencyKey": "idem_01J5EXAMPLE0000000000000",
"subaccountId": "6789012345678"
}'Responses
{
"acceptedAtTsNs": "1735689600000000000",
"amountE18": {
"hi": "1",
"lo": "1"
},
"assetCode": "USDC",
"assetId": 100,
"destination": {
"rootAccountPublicId": "7563897446546",
"smartAccountAddress": "0x2222222222222222222222222222222222222222",
"subaccountPublicId": "6789012345678"
},
"requestId": "request_01J0EXAMPLE",
"status": "INTERNAL_TRANSFER_STATUS_ACCEPTED",
"transferId": "9155001234569",
"uAssetId": "100"
}transfer.v1.CreateInternalTransferRequesttransfer.v1.CreateInternalTransferResponseOptional source public subaccount ID. When omitted, subaccount-scoped API keys use their bound subaccount; other callers use their authenticated root account.
Destination root account public id.
Destination subaccount public id.
Destination smart-account address.
Canonical public unified asset id for the asset being transferred.
Most significant 64 bits.
Least significant 64 bits.
Stable client-supplied idempotency key used to collapse safe retries.
Stable server-owned request identifier for this intake.
Stable transfer identifier for the settled internal transfer.
Acceptance timestamp in nanoseconds since epoch (server time).
Echoed canonical public unified asset id.
Resolved asset code for convenience.
Resolved unified asset id used by downstream settlement.
Most significant 64 bits.
Least significant 64 bits.
Destination root account public id.
Destination subaccount public id when the destination targets a subaccount.
Destination smart-account address resolved by the server.
Public status for the transfer request.
| 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. |