{"id":20170681,"url":"https://github.com/bitcoinschema/js-1sat-ord","last_synced_at":"2025-09-08T18:34:56.370Z","repository":{"id":162293962,"uuid":"612918456","full_name":"BitcoinSchema/js-1sat-ord","owner":"BitcoinSchema","description":"1Sat JS Library","archived":false,"fork":false,"pushed_at":"2025-06-01T15:48:28.000Z","size":4837,"stargazers_count":25,"open_issues_count":0,"forks_count":15,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-08-09T09:05:24.053Z","etag":null,"topics":["1sat","bitcoin","bitcoinsv","bsv","ordinals"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BitcoinSchema.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-03-12T11:31:06.000Z","updated_at":"2025-06-01T15:48:31.000Z","dependencies_parsed_at":"2024-01-03T13:34:49.453Z","dependency_job_id":"7e958a16-7b84-494e-8dfb-b43337e5bdab","html_url":"https://github.com/BitcoinSchema/js-1sat-ord","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/BitcoinSchema/js-1sat-ord","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BitcoinSchema%2Fjs-1sat-ord","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BitcoinSchema%2Fjs-1sat-ord/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BitcoinSchema%2Fjs-1sat-ord/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BitcoinSchema%2Fjs-1sat-ord/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BitcoinSchema","download_url":"https://codeload.github.com/BitcoinSchema/js-1sat-ord/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BitcoinSchema%2Fjs-1sat-ord/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274229373,"owners_count":25245188,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-08T02:00:09.813Z","response_time":121,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["1sat","bitcoin","bitcoinsv","bsv","ordinals"],"created_at":"2024-11-14T01:20:15.135Z","updated_at":"2025-09-08T18:34:55.971Z","avatar_url":"https://github.com/BitcoinSchema.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"---\ndescription: js-1sat-ord\n---\n\n# 1Sat Ordinals - JS Library\n\nA Javascript library for creating and managing 1Sat Ordinal inscriptions and transactions. Uses `@bsv/sdk` under the hood.\n\nIt provides functions for listing, cancelling and purchasing Ordinal Lock transactions.\n\nIt also privides helpers for fetching utxos for payments, nfts, and tokens.\n\n### Install\n\nInstall the library, and it's peer dependency. We recommend using Bun for the best performance, but you can also use Yarn or npm:\n\n```bash\n# Using Bun (recommended)\nbun add js-1sat-ord @bsv/sdk\n\n# Using Yarn\nyarn add js-1sat-ord @bsv/sdk\n\n# Using npm\nnpm i js-1sat-ord @bsv/sdk\n```\n\n### Usage\n\n```ts\nimport { createOrdinals, sendOrdinals, sendUtxos, deployBsv21Token, transferOrdToken } from 'js-1sat-ord'\n```\n\n### Example\n\nPrepare some utxos to use in the following format. Be sure to use base64 encoded scripts. We use this encoding because it makes large scripts smaller in size.\n\n```ts\nimport type { Utxo } from \"js-1sat-ord\";\n\nconst utxo: Utxo = {\n  satoshis: 269114,\n  txid: \"61fd6e240610a9e9e071c34fc87569ef871760ea1492fe1225d668de4d76407e\",\n  script: \"\u003cbase64 encoded script\u003e\",\n  vout: 1,\n};\n```\n\n You can use the helper `fetchPayUtxos(address)` to fetch unspent transaction outputs from the public 1Sat API and create the scripts with the correct encoding (base64). This should be a BSV address, not your ordinals address. Note: By default the script encoding will be base64, but you can provide a 2nd parameter and specify hex or asm encoding for the script property.\n\n Note: `Utxo` and `NftUtxo` and `TokenUtxo` have an optional `pk` field for specifying a Private Key for unlocking this utxo. This is helpful when multiple keys own the inputs and you need to spend them in a single traqnsaction.\n\n ```ts\n import { fetchPayUtxos } from \"js-1sat-ord\";\n\n const utxos = await fetchPayUtxos(payAddress)\n ```\n\nFor NFTUtxos:\n\n```ts\nimport { fetchNftUtxos } from \"js-1sat-ord\"\n\n// collectionId is optional\nconst collectionId = \"1611d956f397caa80b56bc148b4bce87b54f39b234aeca4668b4d5a7785eb9fa_0\"\nconst nftUtxos = await fetchNftUtxos(ordAddress, collectionId)\n```\n\nFor Token Utxos:\n\n```ts\nimport { fetchTokenUtxos, type TokenType } from \"js-1sat-ord\"\n\nconst protocol = TokenType.BSV21;\nconst tokenId = \"e6d40ba206340aa94ed40fe1a8adcd722c08c9438b2c1dd16b4527d561e848a2_0\";\nconst tokenUtxos = await fetchTokenUtxos(protocol, tokenId, ordAddress);\n```\n\n#### Prepare Inscription\n\nFor a markdown inscription, you can create a string and convert it to base64:\n\n```ts\nimport type { Inscription } from \"js-1sat-ord\";\n\n\n// Create a markdown string\nconst markdownContent = \"# Hello World!\\n\\nThis is a 1Sat Ordinal inscription.\";\n\n// Convert to base64\nconst encodedFileData = Buffer.from(markdownContent).toString('base64');\n\n// Prepare the inscription object\nconst inscription: Inscription = {\n  dataB64: encodedFileData,\n  contentType: \"text/markdown\"\n};\n```\n\n#### Prepare Keys\n\nBe sure to use different keys for ordinals and normal payments:\n\n```ts\nimport { PrivateKey } from \"js-1sat-ord\";\n\nconst paymentPk = PrivateKey.fromWif(paymentWif);\nconst ordPk = PrivateKey.fromWif(ordWif);\n```\n\n### Create Ordinals\n\nThe `createOrdinals` function creates a transaction with inscription outputs:\n\n```ts\nimport type { CreateOrdinalsConfig } from \"js-1sat-ord\";\n\nconst config: CreateOrdinalsConfig = {\n  utxos: [utxo],\n  destinations: [{\n    address: ordinalDestinationAddress,\n    inscription: { dataB64: encodedFileData, contentType: \"text/markdown\" }\n  }],\n  paymentPk: paymentPk\n};\n\nconst result = await createOrdinals(config);\n```\n\n### Send Ordinals\n\nSends ordinals to the given destinations:\n\n```ts\nimport type { SendOrdinalsConfig } from \"js-1sat-ord\";\n\nconst config: SendOrdinalsConfig = {\n  paymentUtxos: [paymentUtxo],\n  ordinals: [ordinalUtxo],\n  paymentPk: paymentPk,\n  ordPk: ordPk,\n  destinations: [{\n    address: destinationAddress,\n    inscription: { dataB64: encodedFileData, contentType: \"text/markdown\" }\n  }]\n};\n\nconst result = await sendOrdinals(config);\n```\n\n### Deploy a BSV21 Token\n\n```ts\nimport type { DeployBsv21TokenConfig } from \"js-1sat-ord\";\n\nconst config: DeployBsv21TokenConfig = {\n  symbol: \"MYTICKER\",\n  icon: \"\u003cicon_outpoint\u003e\",\n  utxos: [utxo],\n  initialDistribution: { address: destinationAddress, tokens: 10 },\n  paymentPk: paymentPk,\n  destinationAddress: destinationAddress\n};\n\nconst result = await deployBsv21Token(config);\n```\n\n### Transfer BSV21 Tokens\n\n```ts\nimport type { TransferBsv21TokenConfig } from \"js-1sat-ord\";\n\nconst config: TransferBsv21TokenConfig = {\n  protocol: TokenType.BSV21,\n  tokenID: tokenID,\n  utxos: [utxo],\n  inputTokens: [tokenUtxo],\n  distributions: [{ address: destinationAddress, tokens: 0.1 }],\n  paymentPk: paymentPk,\n  ordPk: ordPk\n};\n\nconst result = await transferOrdToken(config);\n```\n\nNote: To burn tokens you can set the optional `burn` parameter to `true`\nNote: You can use the optional `splitConfig` parameter to configure how and when to split token change outputs, and whether change outputs should include metadata.\nNote: You can use the optional `tokenInputMode` parameter to configure whether `all` tokens are consumed, or only what's `needed`. Default is `needed`.\n\n### Send Utxos\n\nSends utxos to the given destination:\n\n```ts\nimport type { SendUtxosConfig } from \"js-1sat-ord\";\n\nconst config: SendUtxosConfig = {\n  utxos: [utxo],\n  paymentPk: paymentPk,\n  payments: [{ to: destinationAddress, amount: 1000 }]\n};\n\nconst { tx } = await sendUtxos(config);\n```\n\n### Create Ordinal Listings \nCreates a listing using an \"Ordinal Lock\" script. Can be purchased by anyone by sending a specific amount to the provided address.\n\n```ts\nconst listings = [{\n  payAddress: addressToReceivePayment;\n  price: 100000; // price in satoshis\n  listingUtxo,\n  ordAddress: returnAddressForCancel;\n}]\n\nconst config: CreateOrdListingsConfig = {\n  utxos: [utxo],\n  listings,\n  paymentPk,\n  ordPk,\n}\n\nconst { tx } = await createOrdListings(config);\n```\n\n### Purchase Ordinal Listing\n\n```ts\nconst config: PurchaseOrdListingConfig ={\n  utxos: [utxo], \n  paymentPk, \n  listingUtxo, \n  ordAddress,\n};\n\nconst { tx } = await purchaseOrdListing(config);\n```\n\n### Cancel Ordinal Listings\nSpends the ordinal lock without payment, returning the ordinal to the address specified in the listing contract.\n\n```ts\nconst config: CancelOrdListingsConfig = { utxos, listingUtxos, ordPk, paymentPk };\nconst { tx } = await cancelOrdListings(config);\n```\n\n### Additional Configuration Options\n\nEach function accepts additional configuration options not shown in the examples above. These may include:\n\n- `changeAddress`: Address to send change to (if not provided, defaults to the payment key's address)\n- `satsPerKb`: Satoshis per kilobyte for fee calculation\n- `metaData`: MAP (Magic Attribute Protocol) metadata to include in inscriptions\n- `signer`: Custom signer object for transaction signing\n- `additionalPayments`: Additional payments to include in the transaction\n\nRefer to the function documentation for a complete list of configuration options for each function.\n\n### Broadcasting\n\n```ts\nimport { oneSatBroadcaster } from \"js-1sat-ord\"\n\n// ...\n\nconst { status, txid, message  } = await tx.broadcast(oneSatBroadcaster())\n```\n\n#### Using with Bundlers\n\nSince this package depends on `@bsv/sdk` there should be no issue with bundlers.\n\n## Resources\nThere is a public 1Sat API which is documented here:\n\n[https://ordinals.gorillapool.io/api/docs](https://ordinals.gorillapool.io/api/docs)\n\n---","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitcoinschema%2Fjs-1sat-ord","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbitcoinschema%2Fjs-1sat-ord","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitcoinschema%2Fjs-1sat-ord/lists"}