Intent request structure

Use this page to understand the request body structure for intent proposals, dry runs, and signatures. For an introduction to the concept of intents, see Intents and approvals.

An intent is a request to execute an action, which executes once it has the approvals its matching policy requires. For the full execution lifecycle, see Intents and approvals.

The submitter of an intent defines, in particular, the following fields:

• payload, which sets the type of the intent and the details of the operation to process;
• expiryAt, which sets an expiration time to the intent;
• targetDomainId, which sets the domain in which to execute the intent (either in the current domain or within a descendant domain);
• type, which defines whether the request is an original user-signed submission (Propose), a system-signed submission (SystemSigned), an intention to approve an existing intent (Approve), or an intention to reject an existing intent (Reject).

There exist four intent types for most entities in the system, as prefixed by:

• Create to create an entity of a given type;
• Update to update the definition of an entity;
• Lock to lock an entity;
• Unlock to unlock an entity.

Exceptions exist, such as for the release of quarantined transfers, which has its dedicated intent called ReleaseQuarantinedTransfers.

A generic intent, named NotarizeData, allows the submission of intents not related to internal processes of Ripple Custody. Such intents may be used to trigger external effects to extend the capabilities of the system, such as to initiate fiat payment orders or trading orders.

There are three request body types covered on this page:

• User-signed proposal request body: Request body to propose a new intent with a user signature.
• System-signed proposal request body: API-only request body to propose an intent without a client-side payload signature.
• Dry run and signature request body: Request body to perform a dry run of a user-signed intent proposal, or add a signature to the user-signed proposal request body.

Both types include the same set of standard fields and fields that are specific to the intent type.

You can see an example of each request body type in the examples below.

The data you need to specify in your request is as follows:

All the properties that are specific to the type of intent being created (create a domain, update some user details, and so on) are inside the payload block.

You can see examples of payload blocks in the following sections:

• Manage vaults
• Manage accounts with the API
• Manage endpoints
• Manage tokens with the API
• Send assets with the API

The following example shows the request body needed to propose an endpoint creation intent:

{
    "request": {
        "author": {
            "id": "9b672a12-37d1-456a-8d35-57426090a156",
            "domainId": "9067d363-6411-498b-a32b-15d230a86706"
        },
        "expiryAt": "2022-11-19T16:00:01.621Z",
        "targetDomainId": "9067d363-6411-498b-a32b-15d230a86706",
        "id": "00baa536-421e-11ee-be56-0242ac120002",
        "payload": {
            "id": "202c33d0-421e-11ee-be56-0242ac120002",
            "address": "0xD135295cC7562593995202638b8509ba3d108e1",
            "trustScore": 100,
            "ledgerId": "avalanche-chain-testnet-fuji",
            "alias": "New endpoint",
            "lock": "Unlocked",
            "customProperties": {},
            "type": "v0_CreateEndpoint"
        },
        "description": "Test endpoint create",
        "customProperties": {},
        "type": "Propose"
    },
    "signature": "<SIGNATURE>"
}

System-signed proposal submission is available only through the API. The caller authenticates with a bearer token. The request body does not include request.author or a top-level signature.

{
    "request": {
        "type": "SystemSigned",
        "targetDomainId": "9067d363-6411-498b-a32b-15d230a86706",
        "id": "00baa536-421e-11ee-be56-0242ac120002",
        "expiryAt": "2026-06-30T15:30:00.000Z",
        "payload": {
            "type": "v0_CreateTransactionOrder",
            "...": "payload-specific fields"
        },
        "description": "Service-submitted transaction order",
        "customProperties": {}
    }
}

System-signed proposals are matched by policies that use intentOrigin: "SystemSigned". If no matching policy applies, the intent cannot execute. Approvals and rejections still use user-signed request bodies.

Before submitting this request body, the active Gateway system signing public key must be registered in Notary, NOTARY_SYSTEM_SIGNED_INTENTS_ENABLED must be set to enabled: true, and the target domain must have a matching SystemSigned policy. For the full setup sequence, see System-signed intent configuration.

The following example shows the subset of the User-signed proposal request body needed to:

• Perform a dry run of an endpoint creation intent.
• Generate the cryptographic signature for a user-signed endpoint creation intent proposal.

The dry-run API request body uses the user-signed shape and includes an author. The OpenAPI specification does not define a system-signed dry-run request body. The type: "Propose" field belongs to the proposal object you sign; the dry-run request schema itself does not define a type field.

{
    "author": {
        "id": "9b672a12-37d1-456a-8d35-57426090a156",
        "domainId": "9067d363-6411-498b-a32b-15d230a86706"
    },
    "expiryAt": "2022-11-19T16:00:01.621Z",
    "targetDomainId": "9067d363-6411-498b-a32b-15d230a86706",
    "id": "00baa536-421e-11ee-be56-0242ac120002",
    "payload": {
        "id": "202c33d0-421e-11ee-be56-0242ac120002",
        "address": "0xD135295cC7562593995202638b8509ba3d108e1",
        "trustScore": 100,
        "ledgerId": "avalanche-chain-testnet-fuji",
        "alias": "New endpoint",
        "lock": "Unlocked",
        "customProperties": {},
        "type": "v0_CreateEndpoint"
    },
    "description": "Test endpoint create",
    "customProperties": {},
    "type": "Propose"
}