Create an idempotent wallet-authorized transfer intent.
POST /api/v1/wallet/transfers/prepare. Create an idempotent wallet-authorized transfer intent.
Request
POST /api/v1/wallet/transfers/prepare
Authentication is required. Supported credentials: a signed-in customer session token in Authorization: Bearer …. This route does not accept customer API keys.
Parameters
| Name | In | Type | Required | Constraints | Description |
|---|---|---|---|---|---|
Idempotency-Key | header | string | Yes | min length: 8; max length: 256; pattern: ^[A-Za-z0-9._:-]+$ | — |
X-Service-Act-As | header | string | No | min length: 3; max length: 512 | Service-principal path only (local and devnet stages; refused by configuration on mainnet). With an OAuth client-credentials bearer token from the validator, names the allow-listed Party the client acts as. Missing: 400 SERVICE_ACT_AS_REQUIRED; not allow-listed: 403 SERVICE_PARTY_NOT_ALLOWED. Ignored for customer session tokens. |
X-Request-Id | header | string | No | min length: 8; max length: 128; pattern: ^[A-Za-z0-9._:-]+$ | Optional client correlation identifier. The server always generates a separate authoritative request ID and retains a valid supplied value only as secondary audit correlation metadata. |
Request body
A body is required.
Content type: application/json
Type: object.
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
amount | string | Yes | pattern: ^(?:0|[1-9]\d{0,27})(?:\.\d{1,10})?$ | — |
instrumentId | object · Schema 1 | Yes | — | — |
memo | string | No | min length: 1; max length: 280 | — |
recipientPartyId | string | Yes | min length: 3; max length: 512 | Opaque, case-sensitive Canton Party ID containing 3-512 Unicode scalar values with no normalization, edge whitespace, or C0/C1 control characters. |
walletConnectionId | string | Yes | format: uuid; pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ | — |
Additional fields are not allowed.
cURL
Create request.json using the request-body schema. The example sends the file bytes unchanged.
curl --fail-with-body --silent --show-error \
--request POST \
--url "https://launch-api.supanova.app/api/v1/wallet/transfers/prepare" \
--header "Authorization: Bearer $SUPANOVA_SESSION_TOKEN" \
--header "Idempotency-Key: $IDEMPOTENCY_KEY" \
--header "Content-Type: application/json" \
--data-binary @request.jsonResponses
201
A wallet-neutral action and operation.
| Header | Type | Description |
|---|---|---|
X-Request-Id | string | Server-generated request correlation identifier to retain for support and reconciliation. |
Content type: application/json
Type: object.
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
execution | "simulated" | Yes | — | — |
fee | object · Schema 2 | Yes | — | — |
feeLineItems | array of object · Schema 3 | Yes | — | — |
operation | object · Schema 4 | Yes | — | — |
walletAction | object · Schema 5 | Yes | — | — |
Additional fields are not allowed.
400
The request is malformed or failed validation. Codes: VALIDATION_FAILED, IDEMPOTENCY_KEY_REQUIRED, AMBIGUOUS_CREDENTIALS, SERVICE_ACT_AS_REQUIRED.
| Header | Type | Description |
|---|---|---|
X-Request-Id | string | Server-generated request correlation identifier to retain for support and reconciliation. |
Content type: application/json
Standard envelope: error.code, error.message, optional error.details, and requestId. See error handling and the full code registry.
401
Credentials are missing, malformed, expired or revoked. Codes: AUTHENTICATION_REQUIRED, INVALID_AUTHORIZATION_HEADER, INVALID_ACCESS_TOKEN, SESSION_REVOKED.
| Header | Type | Description |
|---|---|---|
X-Request-Id | string | Server-generated request correlation identifier to retain for support and reconciliation. |
Content type: application/json
Standard envelope: error.code, error.message, optional error.details, and requestId. See error handling and the full code registry.
403
The credential may not call this route. Codes: ACCOUNT_RESTRICTED, ANONYMOUS_ACCOUNT_NOT_ALLOWED, API_KEY_ROUTE_NOT_ALLOWED, SERVICE_PARTY_NOT_ALLOWED, SERVICE_PRINCIPAL_NOT_ALLOWED, SIGNUP_NOT_INVITED.
| Header | Type | Description |
|---|---|---|
X-Request-Id | string | Server-generated request correlation identifier to retain for support and reconciliation. |
Content type: application/json
Standard envelope: error.code, error.message, optional error.details, and requestId. See error handling and the full code registry.
409
The request conflicts with current state, or the Idempotency-Key was reused with a different request (IDEMPOTENCY_KEY_CONFLICT; the former IDEMPOTENCY_CONFLICT is a deprecated alias, no longer returned, that clients handle the same way for one release). Codes: IDEMPOTENCY_KEY_CONFLICT, IDEMPOTENCY_CONFLICT.
| Header | Type | Description |
|---|---|---|
X-Request-Id | string | Server-generated request correlation identifier to retain for support and reconciliation. |
Content type: application/json
Standard envelope: error.code, error.message, optional error.details, and requestId. See error handling and the full code registry.
413
The request body exceeds the size limit.
| Header | Type | Description |
|---|---|---|
X-Request-Id | string | Server-generated request correlation identifier to retain for support and reconciliation. |
Content type: application/json
Standard envelope: error.code, error.message, optional error.details, and requestId. See error handling and the full code registry.
428
The signed-in account must accept the current product terms first. Codes: PRODUCT_LEGAL_ACCEPTANCE_REQUIRED.
| Header | Type | Description |
|---|---|---|
X-Request-Id | string | Server-generated request correlation identifier to retain for support and reconciliation. |
Content type: application/json
Standard envelope: error.code, error.message, optional error.details, and requestId. See error handling and the full code registry.
429
The caller exceeded an IP or principal request budget.
| Header | Type | Description |
|---|---|---|
Retry-After | integer | Whole seconds to wait before retrying a rate-limited request. |
X-Request-Id | string | Server-generated request correlation identifier to retain for support and reconciliation. |
Content type: application/json
Standard envelope: error.code, error.message, optional error.details, and requestId. See error handling and the full code registry.
503
A dependency is unavailable or the feature is not enabled on this deployment. Codes: AUTHENTICATION_UNAVAILABLE, AUTHORIZATION_UNAVAILABLE.
| Header | Type | Description |
|---|---|---|
X-Request-Id | string | Server-generated request correlation identifier to retain for support and reconciliation. |
Content type: application/json
Standard envelope: error.code, error.message, optional error.details, and requestId. See error handling and the full code registry.
default
Machine-readable API error. The HTTP status identifies the error class.
| Header | Type | Description |
|---|---|---|
X-Request-Id | string | Server-generated request correlation identifier to retain for support and reconciliation. |
Content type: application/json
Standard envelope: error.code, error.message, optional error.details, and requestId. See error handling and the full code registry.
Nested schemas
Field links above lead to the complete nested object, array, and variant definitions below. Required fields are scoped to their containing object.
Schema 1
Request body.instrumentId
Type: object.
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
admin | string | Yes | min length: 1; max length: 512 | — |
id | string | Yes | min length: 1; max length: 512 | — |
Additional fields are not allowed.
Schema 2
Response 201.fee
Type: object.
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
amount | string | Yes | pattern: ^(?:0|[1-9]\d{0,27})(?:\.\d{1,10})?$ | — |
asset | object · Schema 1 | Yes | — | — |
policy | "cip-0078-no-cc-transfer-fee" | Yes | — | — |
Additional fields are not allowed.
Schema 3
Response 201.feeLineItems
Type: array of object.
Array items: object · Schema 6.
Schema 4
Response 201.operation
Type: object.
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
expiresAt | string | Yes | — | — |
id | string | Yes | format: uuid; pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ | — |
status | string | Yes | allowed: "received", "validating", "awaiting_signature", "ready", "submitted", "confirmed", "failed", "rejected", "expired", "cancelled" | — |
Additional fields are not allowed.
Schema 5
Response 201.walletAction
Type: object.
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
expiresAt | string | Yes | — | — |
intent | object · Schema 7 | Yes | — | — |
kind | "canton.prepare-execute" | Yes | — | — |
method | "prepareExecute" | Yes | — | — |
networkId | string | Yes | pattern: ^canton:[-_a-zA-Z0-9]{1,32}$ | — |
operationId | string | Yes | format: uuid; pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ | — |
readiness | string | Yes | allowed: "daml-command-builder-not-configured", "ready" | — |
request | one or more variants · Schema 8 | Yes | — | — |
standard | "CIP-0103" | Yes | — | — |
Additional fields are not allowed.
Schema 6
Response 201.feeLineItems item
Type: object.
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
amount | string | Yes | pattern: ^(?:0|[1-9]\d{0,27})(?:\.\d{1,10})?$ | — |
instrument | object · Schema 1 | Yes | — | — |
kind | "transfer" | Yes | — | — |
label | string | Yes | — | — |
Additional fields are not allowed.
Schema 7
Response 201.walletAction.intent
Type: object.
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
amount | string | Yes | pattern: ^(?:0|[1-9]\d{0,27})(?:\.\d{1,10})?$ | — |
feeAmountCc | string | Yes | pattern: ^(?:0|[1-9]\d{0,27})(?:\.\d{1,10})?$ | — |
instrumentId | object · Schema 1 | Yes | — | — |
memo | string | No | — | — |
recipientPartyId | string | Yes | — | — |
senderPartyId | string | Yes | — | — |
type | "transfer.execute" | Yes | — | — |
Additional fields are not allowed.
Schema 8
Response 201.walletAction.request
Type: one or more variants.
At least one of these variants must match:
- Variant 1: object · Schema 9.
- Variant 2: null.
Schema 9
Response 201.walletAction.request variant 1
Type: object.
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
kind | string | Yes | allowed: "application-submission", "interactive-submission", "wallet-submission" | — |
commandId | string | Yes | min length: 1; max length: 255 | — |
actAs | array of string · Schema 10 | Yes | min items: 1; max items: 8 | — |
synchronizerId | string | Yes | min length: 1; max length: 512 | — |
hashingSchemeVersion | string | Yes | min length: 1; max length: 64 | — |
signatureFormat | "SIGNATURE_FORMAT_RAW" | Yes | — | — |
signingAlgorithmSpec | "SIGNING_ALGORITHM_SPEC_ED25519" | Yes | — | — |
signedBy | one or more variants · Schema 11 | Yes | — | — |
preparedTransaction | one or more variants · Schema 12 | Yes | — | — |
preparedTransactionHash | one or more variants · Schema 13 | Yes | — | — |
Additional fields are not allowed.
Schema 10
Response 201.walletAction.request variant 1.actAs
Type: array of string.
min items: 1; max items: 8
Array items: string. min length: 3; max length: 512
Schema 11
Response 201.walletAction.request variant 1.signedBy
Type: one or more variants.
At least one of these variants must match:
- Variant 1: string. min length:
4; max length:160 - Variant 2: null.
Schema 12
Response 201.walletAction.request variant 1.preparedTransaction
Type: one or more variants.
At least one of these variants must match:
- Variant 1: string. max length:
4194304 - Variant 2: null.
Schema 13
Response 201.walletAction.request variant 1.preparedTransactionHash
Type: one or more variants.
At least one of these variants must match:
- Variant 1: string. max length:
512 - Variant 2: null.
Source contract
This page is generated from the checked-in customer OpenAPI snapshot. Download JSON, download YAML, or compare the live API reference. Snapshot provenance records the retrieval date and checksum.