ReferenceAPI ReferenceSymbol

Create symbol

POST/symbols●Define a new unit of exchange in the ledger.

The factor must be a power of 10. Common values: 100 for fiat currencies like USD and EUR, 1 for currencies without subdivisions like JPY, and 100000000 for Bitcoin (satoshis).

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

POST
/symbols

Usage Examples

curl -X POST "http://localhost:3000/v2/symbols" \  -H "x-ledger: <YOUR LEDGER HANDLE>" \  -H "Content-Type: application/json" \  -d '{    "hash": "d8ba7197becbb432ccc0400d176f14d45e70176c13fcf51b68bd3b471875ce8a",    "data": {      "handle": "usd",      "factor": 100    },    "meta": {      "proofs": [        {          "method": "ed25519-v2",          "digest": "471f3fb93a190089f116977d0837cb93bec66684d29ae0486a4e885df51d73a2",          "public": "AN6XpZ7T8FDCkjbSpIVE2cioQ7hajp8DBTOioz/TSZ8=",          "result": "hp/s6DeY6k2Csx2lbgoT0P4fMYoD6GTHjsRnbTPcklAzo9eyPDpV0S598T+Mv8sp0QyeEHcGj0pNttnMMDtFCg==",          "custom": {            "moment": "2025-04-05T14:30:00.000Z",            "status": "created"          }        }      ]    }  }'
{
  "luid": "$sym.-01xK8nRqT2dS4wX3",
  "hash": "d8ba7197becbb432ccc0400d176f14d45e70176c13fcf51b68bd3b471875ce8a",
  "data": {
    "handle": "usd",
    "factor": 100
  },
  "meta": {
    "status": "created",
    "moment": "2025-04-05T14:30:00.050Z",
    "owners": [
      "AN6XpZ7T8FDCkjbSpIVE2cioQ7hajp8DBTOioz/TSZ8="
    ],
    "proofs": [
      {
        "signer": "ach-admin",
        "method": "ed25519-v2",
        "digest": "471f3fb93a190089f116977d0837cb93bec66684d29ae0486a4e885df51d73a2",
        "public": "AN6XpZ7T8FDCkjbSpIVE2cioQ7hajp8DBTOioz/TSZ8=",
        "result": "hp/s6DeY6k2Csx2lbgoT0P4fMYoD6GTHjsRnbTPcklAzo9eyPDpV0S598T+Mv8sp0QyeEHcGj0pNttnMMDtFCg==",
        "custom": {
          "moment": "2025-04-05T14:30:00.000Z",
          "status": "created"
        }
      },
      {
        "signer": "system",
        "method": "ed25519-v2",
        "digest": "caca7516ee43f7cc71f915027e7fe80c88a1f2dad0ff5939e5051c14f53c399d",
        "public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
        "result": "aZ+5+qHFAuy66BpaW/4ActjpyuA7o4E02EEw4b9Fz185yZ+Ox2wmGScH8if/5Geyfnxz2pMtQvSBtTJJaol8Cg==",
        "custom": {
          "luid": "$sym.-01xK8nRqT2dS4wX3",
          "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

Symbol body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

Symbol

Define units of exchange like currencies, points, or any countable value.

List symbols GET

Use this endpoint to review defined currencies and units of exchange, or find symbols by schema. Supported filters: - `data.schema` — symbol schema - `meta.status` — record status - `meta.labels` — record labels - `meta.domain` — domain scope - `data.custom.<field>` — any custom field (may be slower on large datasets)