ReferenceAPI ReferenceIntent

Get intent

GET/intents/{id}●Retrieve an intent by its handle or LUID.

The response includes the current DTC status and all proofs collected so far, which can be used to track processing progress.

GET
/intents/{id}

Usage Examples

curl -X GET "http://localhost:3000/v2/intents/<HANDLE>" \  -H "x-ledger: <YOUR LEDGER HANDLE>"
{
  "luid": "$int.-01xK0rStT2dS4wX3",
  "hash": "be40db4425c914903888398a39519b6e9c9b0e047afd40c64f78c95f8f6d64f1",
  "data": {
    "handle": "transfer-1712345678901",
    "claims": [
      {
        "action": "transfer",
        "source": {
          "handle": "svgs:1001001212@tesla-bank.com",
          "custom": {
            "name": "John Doe",
            "idType": "nidn",
            "idNumber": "123456789",
            "entityType": "individual"
          }
        },
        "target": {
          "handle": "tran:1001001234@nova-bank.com",
          "custom": {
            "name": "Jane Smith",
            "idType": "nidn",
            "idNumber": "987654321",
            "entityType": "individual"
          }
        },
        "amount": 500,
        "symbol": {
          "handle": "usd"
        }
      }
    ]
  },
  "meta": {
    "status": "created",
    "moment": "2025-04-05T14:30:00.050Z",
    "owners": [
      "RyXTVL6wSgoBMSZRmTnnKBc82dQGLn5y4Nlp8KRwMLA="
    ],
    "proofs": [
      {
        "signer": "tesla-bank-bridge",
        "method": "ed25519-v2",
        "digest": "6470993982c70f230a95d9084a2ae7b86e612efa57d9f9de9fc379a32923646f",
        "public": "RyXTVL6wSgoBMSZRmTnnKBc82dQGLn5y4Nlp8KRwMLA=",
        "result": "VUq9NdRZcIk/g85nQTDqsAloXEs6tceZZWw3yPzMeiohjZiZ+FK1lHgQY4haI2C+ZzDMD/lTcqpihKPOq82VBg==",
        "custom": {
          "moment": "2025-04-05T14:30:00.000Z",
          "status": "created"
        }
      },
      {
        "signer": "system",
        "method": "ed25519-v2",
        "digest": "7b75a12a0a9f29fb903461a2c9d1e4d50e7092199c7bef460e6550e09056d7ac",
        "public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
        "result": "rAiwYdEpgfJK7Cd3nYLJgrM/YTKphjh6gPAh6+z2Wm6IYubg+2CbyJAjKSp69T+bQikHqGAYypy2eUTG/7u6CQ==",
        "custom": {
          "luid": "$int.-01xK0rStT2dS4wX3",
          "moment": "2025-04-05T14:30:00.050Z",
          "status": "created"
        }
      }
    ]
  }
}
{
  "hash": "b7eb7ccf5ffc126951e13e29a8dcfdaf95db859715d4edfc2d16f59a79d4cd58",
  "data": {
    "reason": "auth.unauthorized",
    "detail": "Invalid token."
  },
  "meta": {
    "proofs": [
      {
        "signer": "system",
        "method": "ed25519-v2",
        "digest": "3acece870c4118bfe4223118e4d2f3cfd5b8947a7093785b66d49aa57fa2890a",
        "public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
        "result": "gnK63DqqWDY/UXvnZHixDKPKS6tfeGHgdARylnPiJLwQGyYxuD97TYbSg2wrzsf/bDrHwQYZaf8Gu5ryYP0UAA==",
        "custom": {
          "moment": "2025-04-05T14:30:00.000Z"
        }
      }
    ]
  }
}
{
  "hash": "9ec02726b50650add8acfd124c6defeb978a9ac252a5de888f9493ddc701e927",
  "data": {
    "reason": "auth.forbidden",
    "detail": "Request is not authorized"
  },
  "meta": {
    "proofs": [
      {
        "signer": "system",
        "method": "ed25519-v2",
        "digest": "4f8cbdc38d73348de0c31805c783c84a0fecc6be736d7e187004ba68cd00e675",
        "public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
        "result": "P3hRnveehtuobb4AIO56XBmiduvmYJbpdmOHltG/IifBEH7QSWdv/0pqled4SO9x1Ne3oXuWxJy40DzMvx1MBA==",
        "custom": {
          "moment": "2025-04-05T14:30:00.000Z"
        }
      }
    ]
  }
}
{
  "hash": "d6c59a6df7165fa4a75159799ca5f5e26e544cbb8769eced3d35d8021f6f7935",
  "data": {
    "reason": "record.not-found",
    "detail": "Signer not found"
  },
  "meta": {
    "proofs": [
      {
        "signer": "system",
        "method": "ed25519-v2",
        "digest": "78cf86f34aefcf9da6ed4167a38aac0a2739f68f7bafb1d3e033c01ed1b6cdf1",
        "public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
        "result": "9Ledk+/iAAtj+uLjGe2afq4kID7n8UQD6UpRpLBCujxFjxddq0uZ2tnYRTAXmYdHDkbF0uXqtNM9qO3xhEtpAA==",
        "custom": {
          "moment": "2025-04-05T14:30:00.000Z"
        }
      }
    ]
  }
}

{
  "hash": "1c084e8dcfb9bb84bc8ea96e9e137b149a34b2bbd85f8e60b4263f5aba980476",
  "data": {
    "custom": {
      "errors": [
        {
          "instancePath": "/handle",
          "schemaPath": "#/properties/handle/pattern",
          "keyword": "pattern",
          "params": {
            "pattern": "^[a-zA-Z0-9_\\-+.]+$"
          },
          "message": "must match pattern \"^[a-zA-Z0-9_\\-+.]+$\""
        }
      ]
    },
    "reason": "record.schema-invalid",
    "detail": "Schema validator error: data.handle must match pattern \"^[a-zA-Z0-9_\\-+.]+$\""
  },
  "meta": {
    "proofs": [
      {
        "signer": "system",
        "method": "ed25519-v2",
        "digest": "7a5febb431719b6f43d7e88e79211308e16ac651b71b339276373fdb4e7c3760",
        "public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
        "result": "2/1zYw4AaIzsIHfOIC6V/CHw6owbjYHt48cwmFOig0ibeT0IbojLmj1RCRi8W00ka0udPa9WsacWDd7ObMY8CA==",
        "custom": {
          "moment": "2025-04-05T14:30:00.000Z"
        }
      }
    ]
  }
}

{
  "hash": "93a5f4d97a42c2df97f827c58ff7768d02568c15aca931e22b81fa3160ba0df3",
  "data": {
    "reason": "api.unexpected-error",
    "detail": "An unexpected error occurred"
  },
  "meta": {
    "proofs": [
      {
        "signer": "system",
        "method": "ed25519-v2",
        "digest": "efaf5360143b586917d9636779ad6e08571c5b06909a20dd0f5eba4bf3be7eae",
        "public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
        "result": "hERh6Aecj59iR+Fb25OQsHJScOi4t8EiffKSfjlMQdjHMccTnfDlgZFdaJzXzUtpSwy/NHq0l+7ydh3HSWCoAg==",
        "custom": {
          "moment": "2025-04-05T14:30:00.000Z"
        }
      }
    ]
  }
}

Path Parameters

id*|

The unique identifier of the record - it is luid or handle (address).

Header Parameters

x-ledger?|

The unique identifier of ledger in context for multi tenant requests.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

List intents GET

Use this endpoint to track payment status or investigate failed or stuck payments. For historical data exports and reconciliation, use reports instead. Supported filters: - `meta.status` — lifecycle state - `data.claims.action` — claim type (`transfer`, `issue`, `destroy`, `limit`) - `data.claims.source.handle` — source address - `data.claims.target.handle` — target address - `data.claims.symbol.handle` — symbol - `data.claims.amount` — claim amount (supports range operators) - `data.schema` — intent schema - `meta.labels` — record labels - `meta.domain` — domain scope - `data.custom.<field>` — any custom field (may be slower on large datasets)

Add intent proof POST

Appends a signed proof to the intent record. The proof must be signed against the record's current hash — see [About Proofs](/ledger/structuring-data/about-proofs) for how signing and validation work. Proofs drive the intent through its DTC lifecycle. Each proof carries a status that may trigger a state transition: `pending` → `prepared` → `committed` → `completed` If a bridge reports a failure, the intent transitions through `failed` → `aborted` → `rejected`. Status policies can introduce additional statuses into the lifecycle. Returns the updated record with the new proof in `meta.proofs`. Broadcasts the `intent-proofs-added` signal. Use [effects](/ledger/reference/api/effect) to subscribe.