ReferenceAPI ReferenceIntent

Create intent

POST/intents●Submit a payment intent to move balances between wallets.

The intent starts in pending status and enters the DTC flow. If source or target wallets have bridges assigned, each bridge must prepare the claim before the ledger commits it. Without bridges, the intent transitions through the full lifecycle almost instantly since there is no coordination with external systems.

Status policies can customize the lifecycle by defining quorum requirements for each transition or introducing additional statuses.

Intents cannot be updated after creation. Use proofs to advance the intent through its lifecycle or to record bridge responses.

The handle must be unique within the ledger and can be used as a client-side idempotency key.

Broadcasts the intent-created signal. Use effects to subscribe.

POST
/intents

Usage Examples

curl -X POST "http://localhost:3000/v2/intents" \  -H "x-ledger: <YOUR LEDGER HANDLE>" \  -H "Content-Type: application/json" \  -d '{    "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": {      "proofs": [        {          "method": "ed25519-v2",          "digest": "6470993982c70f230a95d9084a2ae7b86e612efa57d9f9de9fc379a32923646f",          "public": "RyXTVL6wSgoBMSZRmTnnKBc82dQGLn5y4Nlp8KRwMLA=",          "result": "VUq9NdRZcIk/g85nQTDqsAloXEs6tceZZWw3yPzMeiohjZiZ+FK1lHgQY4haI2C+ZzDMD/lTcqpihKPOq82VBg==",          "custom": {            "moment": "2025-04-05T14:30:00.000Z",            "status": "created"          }        }      ]    }  }'
{
  "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": "dc973d46dd35baa27b0ec5a107e2ee3a8cc57116d086dd868dd0f044a8de7d92",
  "data": {
    "reason": "record.duplicated",
    "detail": "Ledger with handle instant-payments already exists."
  },
  "meta": {
    "proofs": [
      {
        "signer": "system",
        "method": "ed25519-v2",
        "digest": "3e1317cc165d132f95ec2f6374890063c162d905d86b33270f97416f8441a872",
        "public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
        "result": "b+0gSDCUzjEKlZQ/c40yqNpZoyQxCFsbV1Ut5/0zM2wM46xmHMBj3qeo3/GDaFD4NgSNm2G8n1f9c9rfvkl3BA==",
        "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"
        }
      }
    ]
  }
}

Header Parameters

x-ledger?|

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

Request Body

application/json

Intent body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

Intent

Create payment requests that move balances between wallets.

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)