Transfer Between Accounts
Transfers cash between two of the caller’s accounts, atomically. The caller must be authorized to act on both accounts, and both always belong to the caller’s member. An API key must be unrestricted and carry the transfer scope; an account-restricted key cannot transfer, because a transfer always spans two accounts. Rejected if it would overdraw the source account, if the amount is zero, or if the source and destination are the same account. An unknown account, or one the caller cannot use, answers the same 400 as any invalid parameter.
POST
/portfolio/transfersAuthorization
UDX-Access-KeyAPI key · headerrequiredOpaque API key ID.
UDX-Access-TimestampAPI key · headerrequiredUnix time in milliseconds, within 30 seconds of server time.
UDX-Access-SignatureAPI key · headerrequiredStandard-base64 RSA-PSS/SHA-256 signature with a 32-byte salt. Sign `timestamp + METHOD + path`; for requests with a body, append `hex(SHA256(body))`; append `UDX-Idempotency-Key` when it is present.
or
AuthorizationBearer token (JWT) · headerrequiredBearer token for an active signed-in UDX user.
Header parameters
UDX-VersionstringDated API version (YYYY-MM-DD). Omit to use the oldest supported version. An unknown version returns `400`.
max length 10
UDX-Idempotency-KeystringOptional client-generated key that makes a mutation safe to retry. Reuse it only for a byte-identical retry. When present, it is included in the request signature; omitting it disables UDX idempotency for that request.
min length 1 · max length 255
Request body
requiredapplication/jsonfrom_account_idobjectrequiredThe account to debit.
Show propertiesHide properties
objectto_account_idobjectrequiredThe account to credit.
Show propertiesHide properties
objectamountobjectrequiredAmount to transfer, in dollars.
Show propertiesHide properties
objectResponses
200The completed transfer. When an idempotency key was supplied, resending the identical request with the same key replays this response, marked with UDX-Idempotent-Replayed — the funds move only once. Without a key, UDX provides no transport replay guarantee.
transferTransferrequiredA completed transfer between two accounts.
Show propertiesHide properties
from_account_idobjectrequiredThe debited account.
Show propertiesHide properties
objectto_account_idobjectrequiredThe credited account.
Show propertiesHide properties
objectamountobjectrequiredAmount transferred, in dollars.
Show propertiesHide properties
object400The request doesn't conform to this spec.
typestring<uri-reference>A stable URI identifying the error's general category. Usually absent (equivalent to "about:blank" per the RFC); documented rate controls use closed URN values so callers can distinguish same-status retry causes without parsing localized prose.
max length 2048
titlestringrequiredA localized, human-readable summary of the error category. Stable for a given status code and resolved language — clients must not use it as a machine-readable discriminator.
max length 40
statusintegerrequiredThe HTTP status code, repeated from the response itself.
detailstringA localized, human-readable explanation specific to this occurrence. Clients must not parse it for machine-readable information.
max length 500
instancestring<uri-reference>An identifier for this specific occurrence, so it can be correlated with server-side logs if you need to report it.
max length 100
401No valid credential was provided.
typestring<uri-reference>A stable URI identifying the error's general category. Usually absent (equivalent to "about:blank" per the RFC); documented rate controls use closed URN values so callers can distinguish same-status retry causes without parsing localized prose.
max length 2048
titlestringrequiredA localized, human-readable summary of the error category. Stable for a given status code and resolved language — clients must not use it as a machine-readable discriminator.
max length 40
statusintegerrequiredThe HTTP status code, repeated from the response itself.
detailstringA localized, human-readable explanation specific to this occurrence. Clients must not parse it for machine-readable information.
max length 500
instancestring<uri-reference>An identifier for this specific occurrence, so it can be correlated with server-side logs if you need to report it.
max length 100
403The API key lacks the `transfer` scope or is restricted to one account.
typestring<uri-reference>A stable URI identifying the error's general category. Usually absent (equivalent to "about:blank" per the RFC); documented rate controls use closed URN values so callers can distinguish same-status retry causes without parsing localized prose.
max length 2048
titlestringrequiredA localized, human-readable summary of the error category. Stable for a given status code and resolved language — clients must not use it as a machine-readable discriminator.
max length 40
statusintegerrequiredThe HTTP status code, repeated from the response itself.
detailstringA localized, human-readable explanation specific to this occurrence. Clients must not parse it for machine-readable information.
max length 500
instancestring<uri-reference>An identifier for this specific occurrence, so it can be correlated with server-side logs if you need to report it.
max length 100
409This key is still in use or its response cannot be replayed. The mutation may have run; check `detail` before retrying.
typestring<uri-reference>A stable URI identifying the error's general category. Usually absent (equivalent to "about:blank" per the RFC); documented rate controls use closed URN values so callers can distinguish same-status retry causes without parsing localized prose.
max length 2048
titlestringrequiredA localized, human-readable summary of the error category. Stable for a given status code and resolved language — clients must not use it as a machine-readable discriminator.
max length 40
statusintegerrequiredThe HTTP status code, repeated from the response itself.
detailstringA localized, human-readable explanation specific to this occurrence. Clients must not parse it for machine-readable information.
max length 500
instancestring<uri-reference>An identifier for this specific occurrence, so it can be correlated with server-side logs if you need to report it.
max length 100
422This key belongs to a different request.
typestring<uri-reference>A stable URI identifying the error's general category. Usually absent (equivalent to "about:blank" per the RFC); documented rate controls use closed URN values so callers can distinguish same-status retry causes without parsing localized prose.
max length 2048
titlestringrequiredA localized, human-readable summary of the error category. Stable for a given status code and resolved language — clients must not use it as a machine-readable discriminator.
max length 40
statusintegerrequiredThe HTTP status code, repeated from the response itself.
detailstringA localized, human-readable explanation specific to this occurrence. Clients must not parse it for machine-readable information.
max length 500
instancestring<uri-reference>An identifier for this specific occurrence, so it can be correlated with server-side logs if you need to report it.
max length 100
429The Member's request rate is exhausted. Wait for `Retry-After`.
typestring<uri-reference>A stable URI identifying the error's general category. Usually absent (equivalent to "about:blank" per the RFC); documented rate controls use closed URN values so callers can distinguish same-status retry causes without parsing localized prose.
max length 2048
titlestringrequiredA localized, human-readable summary of the error category. Stable for a given status code and resolved language — clients must not use it as a machine-readable discriminator.
max length 40
statusintegerrequiredThe HTTP status code, repeated from the response itself.
detailstringA localized, human-readable explanation specific to this occurrence. Clients must not parse it for machine-readable information.
max length 500
instancestring<uri-reference>An identifier for this specific occurrence, so it can be correlated with server-side logs if you need to report it.
max length 100
500Something went wrong on UDX's side.
typestring<uri-reference>A stable URI identifying the error's general category. Usually absent (equivalent to "about:blank" per the RFC); documented rate controls use closed URN values so callers can distinguish same-status retry causes without parsing localized prose.
max length 2048
titlestringrequiredA localized, human-readable summary of the error category. Stable for a given status code and resolved language — clients must not use it as a machine-readable discriminator.
max length 40
statusintegerrequiredThe HTTP status code, repeated from the response itself.
detailstringA localized, human-readable explanation specific to this occurrence. Clients must not parse it for machine-readable information.
max length 500
instancestring<uri-reference>An identifier for this specific occurrence, so it can be correlated with server-side logs if you need to report it.
max length 100
503The transfer could not be resolved to a definite outcome: request admission or account setup is unavailable, or the transfer's result is unknown. If the request included an idempotency key, check your balances, then retry the identical request with the same key — the funds move at most once. A new key is a new transfer: never mint one to retry an attempt whose outcome is unknown. If no key was supplied, do not retry blindly; reconcile the balances before starting another transfer.
typestring<uri-reference>A stable URI identifying the error's general category. Usually absent (equivalent to "about:blank" per the RFC); documented rate controls use closed URN values so callers can distinguish same-status retry causes without parsing localized prose.
max length 2048
titlestringrequiredA localized, human-readable summary of the error category. Stable for a given status code and resolved language — clients must not use it as a machine-readable discriminator.
max length 40
statusintegerrequiredThe HTTP status code, repeated from the response itself.
detailstringA localized, human-readable explanation specific to this occurrence. Clients must not parse it for machine-readable information.
max length 500
instancestring<uri-reference>An identifier for this specific occurrence, so it can be correlated with server-side logs if you need to report it.
max length 100
Request
curl -X POST "https://{hostname}/portfolio/transfers" \
-H "UDX-Access-Key: API_KEY_ID" \
-H "UDX-Access-Timestamp: UNIX_MILLISECONDS" \
-H "UDX-Access-Signature: BASE64_SIGNATURE" \
-H "Content-Type: application/json" \
-d '{
"from_account_id": "6820943174116859281",
"to_account_id": "9214170797177585522",
"amount": "250.00"
}'const response = await fetch("https://{hostname}/portfolio/transfers", {
method: "POST",
headers: {
"UDX-Access-Key": "API_KEY_ID",
"UDX-Access-Timestamp": "UNIX_MILLISECONDS",
"UDX-Access-Signature": "BASE64_SIGNATURE",
"Content-Type": "application/json"
},
body: JSON.stringify({
"from_account_id": "6820943174116859281",
"to_account_id": "9214170797177585522",
"amount": "250.00"
})
});import requests
response = requests.post(
"https://{hostname}/portfolio/transfers",
headers={
"UDX-Access-Key": "API_KEY_ID",
"UDX-Access-Timestamp": "UNIX_MILLISECONDS",
"UDX-Access-Signature": "BASE64_SIGNATURE",
"Content-Type": "application/json"
},
json={
"from_account_id": "6820943174116859281",
"to_account_id": "9214170797177585522",
"amount": "250.00"
},
)Response
{
"transfer": {
"from_account_id": "6820943174116859281",
"to_account_id": "9214170797177585522",
"amount": "250.00"
}
}{
"title": "Bad Request",
"status": 400,
"detail": "request did not pass validation",
"instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
}{
"title": "Unauthorized",
"status": 401,
"detail": "invalid authentication credentials",
"instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
}{
"title": "Forbidden",
"status": 403,
"detail": "insufficient permissions",
"instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
}{
"title": "Conflict",
"status": 409,
"detail": "a request with this UDX-Idempotency-Key is already in progress",
"instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
}{
"title": "Unprocessable Entity",
"status": 422,
"detail": "UDX-Idempotency-Key was already used for a different request",
"instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
}{
"type": "urn:udx:problem:member-rate-limit-exceeded",
"title": "Too Many Requests",
"status": 429,
"detail": "this member has temporarily exceeded its request rate",
"instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
}{
"title": "Internal Server Error",
"status": 500,
"detail": "internal error",
"instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
}{
"title": "Service Unavailable",
"status": 503,
"detail": "the transfer may or may not have completed; check your balances before retrying",
"instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
}{
"title": "Service Unavailable",
"status": 503,
"detail": "account setup is still being completed; retry later",
"instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
}{
"title": "Service Unavailable",
"status": 503,
"detail": "request admission is temporarily unavailable",
"instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
}