Create an intent

Intents describe all ledger balance movements. Each intent can contain one or more claims. A claim is a statement about an action that a user or a system wants to record in a ledger.

Claims can describe various actions, and number of supported actions is expected to grow over time as new use cases are supported.

All claims that are part of an intent are going to be cleared by the ledger atomically. This means that either all or none of the intent claims are going to be accepted by the ledger.

Currently, supported actions for claims are:

  • issue - used when issuing new balance from symbol to target wallet. This action increases the total value of balances in the system.
  • transfer - used when transfering balance from source to target wallet.
  • destroy - used when destroying a balance from source wallet. This action decreases the total value of balances in the system.
  • limit - used when applying a limit to a wallet. This action will update the limit for the specified metric on the requested wallet.
POST
/intents

Authorization

AuthorizationBearer <token>

JWT signed by private key. The presence of this token is not mandatory. It becomes required through the configuration of authorization access rules that requires a token to grant access. Once sent, the token is validated for its format, signature and expiration, regardless of the presence of access rules.

In: header

Header Parameters

x-ledger?handle | luid

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

Request Body

Intent body

hashhash
Match^[A-Fa-f0-9]{64}$
metaintent-meta
dataintent-data

Response Body

const body = JSON.stringify({
  "hash": "f586b2bbd8f4a08bcbf180c95e23dccfa2445c00e0b4089ea569fcda7feb0478",
  "data": {
    "handle": "wsXqY3mGjR1Hwb6ttXNSi",
    "claims": [
      {
        "action": "transfer",
        "amount": 10000,
        "source": {
          "custom": {
            "name": "Ole",
            "idType": "nidn",
            "idNumber": "sqW_LI7J",
            "entityType": "individual"
          },
          "handle": "svgs:452203815337@teslabank.io"
        },
        "symbol": {
          "handle": "usd"
        },
        "target": {
          "custom": {
            "name": "Brianne",
            "idType": "nidn",
            "idNumber": "KbSZuIhn",
            "entityType": "individual"
          },
          "handle": "tran:254085257323@minka.io"
        }
      }
    ],
    "schema": "transfer",
    "access": [
      {
        "action": "any",
        "signer": {
          "public": "gef6OID0o7ZFGTXutV62mh+zv5kgkFP3QLiR+N7syck="
        }
      }
    ],
    "config": {
      "commit": "auto"
    }
  },
  "meta": {
    "proofs": [
      {
        "method": "ed25519-v2",
        "public": "gef6OID0o7ZFGTXutV62mh+zv5kgkFP3QLiR+N7syck=",
        "digest": "c0d2343289ae589204a80587ae6cd7236ec14cb7d07f89c278f681559e0c75cb",
        "result": "HtGj4yUbtcVW03rOR/ghNO7REbTp6HsBPKlTWyZ+tt2k7GJJTdTp2jccH+7xOv4XaXuFVBEXUI4uqgoGT3k5CA==",
        "custom": {
          "moment": "2025-04-02T05:10:31.616Z",
          "status": "created"
        }
      }
    ]
  }
})

fetch("http://localhost:3000/v2/intents", {
  headers: {
    "x-ledger": "string"
  },
  body
})

{
  "hash": "f586b2bbd8f4a08bcbf180c95e23dccfa2445c00e0b4089ea569fcda7feb0478",
  "data": {
    "handle": "wsXqY3mGjR1Hwb6ttXNSi",
    "claims": [
      {
        "action": "transfer",
        "amount": 10000,
        "source": {
          "custom": {
            "name": "Ole",
            "idType": "nidn",
            "idNumber": "sqW_LI7J",
            "entityType": "individual"
          },
          "handle": "svgs:452203815337@teslabank.io"
        },
        "symbol": {
          "handle": "usd"
        },
        "target": {
          "custom": {
            "name": "Brianne",
            "idType": "nidn",
            "idNumber": "KbSZuIhn",
            "entityType": "individual"
          },
          "handle": "tran:254085257323@minka.io"
        }
      }
    ],
    "schema": "transfer",
    "access": [
      {
        "action": "any",
        "signer": {
          "public": "gef6OID0o7ZFGTXutV62mh+zv5kgkFP3QLiR+N7syck="
        }
      }
    ],
    "config": {
      "commit": "auto"
    }
  },
  "luid": "$int.-084781dXNN8wWR8D",
  "meta": {
    "proofs": [
      {
        "custom": {
          "moment": "2025-04-02T05:10:31.616Z",
          "status": "created"
        },
        "digest": "c0d2343289ae589204a80587ae6cd7236ec14cb7d07f89c278f681559e0c75cb",
        "method": "ed25519-v2",
        "public": "gef6OID0o7ZFGTXutV62mh+zv5kgkFP3QLiR+N7syck=",
        "result": "HtGj4yUbtcVW03rOR/ghNO7REbTp6HsBPKlTWyZ+tt2k7GJJTdTp2jccH+7xOv4XaXuFVBEXUI4uqgoGT3k5CA=="
      },
      {
        "custom": {
          "moment": "2025-04-02T05:10:31.635Z",
          "status": "pending"
        },
        "digest": "90e6c95ccedfa7dc56389616e096d51fa604a535237c4b21c329a68067614788",
        "method": "ed25519-v2",
        "public": "SYqAsweCOCByOQrC9DSjAmIVlyocndNaB/GyjxfQY5U=",
        "result": "aVdagZEOtp8T2U4Nghuj4e8mXAI6rBSVQvuHoxUM6tkezlgZ5v2ATLcDhlxTgHfjZ79j7ovA0Dqvwfqwjr1GBA=="
      },
      {
        "custom": {
          "luid": "$int.-084781dXNN8wWR8D",
          "moment": "2025-04-02T05:10:31.639Z",
          "status": "pending"
        },
        "digest": "daa7350b23e07616d2ac9f0d3520982c3abd85b70d0ccfc91602a6c02a4b81ef",
        "method": "ed25519-v2",
        "public": "SYqAsweCOCByOQrC9DSjAmIVlyocndNaB/GyjxfQY5U=",
        "result": "BcJEL0qY7bt4dtGHLb4ydOylqeLILoLIxOt2XZSFK0wb6Mc3FiEtlPv+IGMEviOZ7PFF0LckEsbJUE8C3M0lCg=="
      }
    ],
    "status": "pending",
    "thread": "-08478DZPWqia20ds",
    "moment": "2025-04-02T05:10:31.635Z",
    "owners": [
      "gef6OID0o7ZFGTXutV62mh+zv5kgkFP3QLiR+N7syck="
    ]
  }
}

{
  "hash": "7846195d1e2f8bc75aa0ab35a238b70dc28c809b8fde33ea7d29e9f8d6d6841b",
  "data": {
    "reason": "auth.unauthorized",
    "detail": "Invalid token."
  },
  "meta": {
    "proofs": [
      {
        "method": "ed25519-v2",
        "public": "JdK8m5SqXGCiZ1TdXQbCe9ECqwL3Kg1UZxj4r9gT+cA=",
        "digest": "7846195d1e2f8bc75aa0ab35a238b70dc28c809b8fde33ea7d29e9f8d6d6841b",
        "result": "X2m5A9Yxh4FRPgj6wgJKN0dYrfgXSq3hx8UX1jnmJ7fVHtQCnAp8MepXDZQhNkMsJd7a9HPk96hmvYXTFcHzAw=="
      }
    ]
  }
}

{
  "hash": "4969e3c012b66d88cec597bf337fc01eab8d651e6ed2d5c40236cc1f7d93435a",
  "data": {
    "reason": "auth.forbidden",
    "detail": "Request is not authorized"
  },
  "meta": {
    "proofs": [
      {
        "method": "ed25519-v2",
        "public": "WAweF9PHlboQoW0z8NqhZXFmzUTaV74NRFAd/aILprE=",
        "digest": "4969e3c012b66d88cec597bf337fc01eab8d651e6ed2d5c40236cc1f7d93435a",
        "result": "0G2gvSfBx6MwPT8ShBaiYx7zwa5Kqc4Cq3S3NXV1m5/ZPozoH/SUouuhi9sQU+f0yo0eX4ygH7PzE3PAdlxsCQ=="
      }
    ]
  }
}

{
  "hash": "9e518d3f4a7c8b67ad43fcf9b6a21e0c5f9b2a5e7d6c3b8a1f4e7d0c9b8a7f5e",
  "data": {
    "reason": "record.duplicated",
    "detail": "Ledger with handle ach already exists."
  },
  "meta": {
    "proofs": [
      {
        "method": "ed25519-v2",
        "public": "QpI4V3K6NzJLbRWCGxdHF7XYT9w2jVkArMpLoFa84s4=",
        "digest": "9e518d3f4a7c8b67ad43fcf9b6a21e0c5f9b2a5e7d6c3b8a1f4e7d0c9b8a7f5e",
        "result": "jR3PQvN7Dy4GcXshzZIa5qd6me9CyiTUwRlJo8fkHpv2jlYE+Hx/D0FSrT2y6MCcSjFnV3dlUmWxJrb5F+kzDQ=="
      }
    ]
  }
}

{
  "hash": "3f6e9d2c5b8a1f4e7d0c3b6a9f2e5d8c1b4a7f0e3d6c9b2a5f8e1d4c7b0a3f6e",
  "data": {
    "reason": "record.schema-invalid",
    "detail": "Schema validator error: data.handle must match pattern \"^[a-zA-Z0-9_\\\\-+.]+$\"",
    "custom": {
      "errors": [
        {
          "instancePath": "/handle",
          "schemaPath": "#/properties/handle/pattern",
          "keyword": "pattern",
          "params": {
            "pattern": "^[a-zA-Z0-9_\\\\-+.]+$"
          },
          "message": "must match pattern \"^[a-zA-Z0-9_\\\\-+.]+$\""
        }
      ]
    }
  },
  "meta": {
    "proofs": [
      {
        "method": "ed25519-v2",
        "public": "vL8jKxm5PqTnJfEaRs2uOdY7gzX4CS9WbHlN3cAiBV0=",
        "digest": "3f6e9d2c5b8a1f4e7d0c3b6a9f2e5d8c1b4a7f0e3d6c9b2a5f8e1d4c7b0a3f6e",
        "result": "uYxJLd2QGkEfT8rP7mCn1lHVzBvIaSK4jFqpO5ZwW9oADnMbg6yeiUsvN3tcXj0RwYxkrq5aLm9f4y2Ko8WwDw=="
      }
    ]
  }
}

{
  "hash": "e1d4c7b0a3f6e9d2c5b8a1f4e7d0c3b6a9f2e5d8c1b4a7f0e3d6c9b2a5f8e1d4",
  "data": {
    "reason": "api.unexpected-error",
    "detail": "An unexpected error occurred"
  },
  "meta": {
    "proofs": [
      {
        "method": "ed25519-v2",
        "public": "KxiLpB3v8VEdmYsT2RwNq5o1Cz9gHJfU4aAySt7D0X8=",
        "digest": "e1d4c7b0a3f6e9d2c5b8a1f4e7d0c3b6a9f2e5d8c1b4a7f0e3d6c9b2a5f8e1d4",
        "result": "LzRmNh7x5TQYoqjw30BKDaZnbGcFUsX8v4tpEsr9P6iW1dyJkVC2uALfY8HdpM3eX9w0On12cqYxEtveKoFZDQ=="
      }
    ]
  }
}