# 1Sat Ordinals - JS Library

A Javascript library for creating and managing 1Sat Ordinal inscriptions and transactions. Uses `@bsv/sdk` under the hood.

It provides functions for listing, cancelling and purchasing Ordinal Lock transactions.

It also privides helpers for fetching utxos for payments, nfts, and tokens.

### Install

Install the library, and it's peer dependency. We recommend using Bun for the best performance, but you can also use Yarn or npm:

```bash
# Using Bun (recommended)
bun add js-1sat-ord @bsv/sdk

# Using Yarn
yarn add js-1sat-ord @bsv/sdk

# Using npm
npm i js-1sat-ord @bsv/sdk
```

### Usage

```ts
import { createOrdinals, sendOrdinals, sendUtxos, deployBsv21Token, transferOrdToken } from 'js-1sat-ord'
```

### Example

Prepare 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.

```ts
import type { Utxo } from "js-1sat-ord";

const utxo: Utxo = {
  satoshis: 269114,
  txid: "61fd6e240610a9e9e071c34fc87569ef871760ea1492fe1225d668de4d76407e",
  script: "<base64 encoded script>",
  vout: 1,
};
```

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.

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 transaction.

```ts
import { fetchPayUtxos } from "js-1sat-ord";

const utxos = await fetchPayUtxos(payAddress)
```

For NFTUtxos:

```ts
import { fetchNftUtxos } from "js-1sat-ord"

// collectionId is optional
const collectionId = "1611d956f397caa80b56bc148b4bce87b54f39b234aeca4668b4d5a7785eb9fa_0"
const nftUtxos = await fetchNftUtxos(ordAddress, collectionId)
```

For Token Utxos:

```ts
import { fetchTokenUtxos, type TokenType } from "js-1sat-ord"

const protocol = TokenType.BSV21;
const tokenId = "e6d40ba206340aa94ed40fe1a8adcd722c08c9438b2c1dd16b4527d561e848a2_0";
const tokenUtxos = await fetchTokenUtxos(protocol, tokenId, ordAddress);
```

#### Prepare Inscription

For a markdown inscription, you can create a string and convert it to base64:

```ts
import type { Inscription } from "js-1sat-ord";


// Create a markdown string
const markdownContent = "# Hello World!\n\nThis is a 1Sat Ordinal inscription.";

// Convert to base64
const encodedFileData = Buffer.from(markdownContent).toString('base64');

// Prepare the inscription object
const inscription: Inscription = {
  dataB64: encodedFileData,
  contentType: "text/markdown"
};
```

#### Prepare Keys

Be sure to use different keys for ordinals and normal payments:

```ts
import { PrivateKey } from "js-1sat-ord";

const paymentPk = PrivateKey.fromWif(paymentWif);
const ordPk = PrivateKey.fromWif(ordWif);
```

### Create Ordinals

The `createOrdinals` function creates a transaction with inscription outputs:

```ts
import type { CreateOrdinalsConfig } from "js-1sat-ord";

const config: CreateOrdinalsConfig = {
  utxos: [utxo],
  destinations: [{
    address: ordinalDestinationAddress,
    inscription: { dataB64: encodedFileData, contentType: "text/markdown" }
  }],
  paymentPk: paymentPk
};

const result = await createOrdinals(config);
```

### Send Ordinals

Sends ordinals to the given destinations:

```ts
import type { SendOrdinalsConfig } from "js-1sat-ord";

const config: SendOrdinalsConfig = {
  paymentUtxos: [paymentUtxo],
  ordinals: [ordinalUtxo],
  paymentPk: paymentPk,
  ordPk: ordPk,
  destinations: [{
    address: destinationAddress,
    inscription: { dataB64: encodedFileData, contentType: "text/markdown" }
  }]
};

const result = await sendOrdinals(config);
```

### Deploy a BSV21 Token

```ts
import type { DeployBsv21TokenConfig } from "js-1sat-ord";

const config: DeployBsv21TokenConfig = {
  symbol: "MYTICKER",
  icon: "<icon_outpoint>",
  utxos: [utxo],
  initialDistribution: { address: destinationAddress, tokens: 10 },
  paymentPk: paymentPk,
  destinationAddress: destinationAddress
};

const result = await deployBsv21Token(config);
```

### Transfer BSV21 Tokens

```ts
import type { TransferBsv21TokenConfig } from "js-1sat-ord";

const config: TransferBsv21TokenConfig = {
  protocol: TokenType.BSV21,
  tokenID: tokenID,
  utxos: [utxo],
  inputTokens: [tokenUtxo],
  distributions: [{ address: destinationAddress, tokens: 0.1 }],
  paymentPk: paymentPk,
  ordPk: ordPk
};

const result = await transferOrdToken(config);
```

Note: To burn tokens you can set the optional `burn` parameter to `true` Note: You can use the optional `splitConfig` parameter to configure how and when to split token change outputs, and whether change outputs should include metadata. Note: You can use the optional `tokenInputMode` parameter to configure whether `all` tokens are consumed, or only what's `needed`. Default is `needed`.

### Send Utxos

Sends utxos to the given destination:

```ts
import type { SendUtxosConfig } from "js-1sat-ord";

const config: SendUtxosConfig = {
  utxos: [utxo],
  paymentPk: paymentPk,
  payments: [{ to: destinationAddress, amount: 1000 }]
};

const { tx } = await sendUtxos(config);
```

### Create Ordinal Listings

Creates a listing using an "Ordinal Lock" script. Can be purchased by anyone by sending a specific amount to the provided address.

```ts
const listings = [{
  payAddress: addressToReceivePayment;
  price: 100000; // price in satoshis
  listingUtxo,
  ordAddress: returnAddressForCancel;
}]

const config: CreateOrdListingsConfig = {
  utxos: [utxo],
  listings,
  paymentPk,
  ordPk,
}

const { tx } = await createOrdListings(config);
```

### Purchase Ordinal Listing

```ts
const config: PurchaseOrdListingConfig ={
  utxos: [utxo], 
  paymentPk, 
  listingUtxo, 
  ordAddress,
};

const { tx } = await purchaseOrdListing(config);
```

### Cancel Ordinal Listings

Spends the ordinal lock without payment, returning the ordinal to the address specified in the listing contract.

```ts
const config: CancelOrdListingsConfig = { utxos, listingUtxos, ordPk, paymentPk };
const { tx } = await cancelOrdListings(config);
```

### Additional Configuration Options

Each function accepts additional configuration options not shown in the examples above. These may include:

* `changeAddress`: Address to send change to (if not provided, defaults to the payment key's address)
* `satsPerKb`: Satoshis per kilobyte for fee calculation
* `metaData`: MAP (Magic Attribute Protocol) metadata to include in inscriptions
* `signer`: LocalSigner or RemoteSigner object for adding Sigma protocol signatures to transactions (provides replay protection)
* `additionalPayments`: Additional payments to include in the transaction

#### Using Sigma Protocol Signatures

Several functions support optional Sigma protocol signatures for replay protection:

```ts
import { PrivateKey } from "@bsv/sdk";

const signerKey = PrivateKey.fromRandom();
const signer = { idKey: signerKey };

// Use with any supported function
const config = {
  // ... other config options
  signer: signer
};
```

Supported functions: `createOrdinals`, `sendOrdinals`, `transferOrdToken`, `deployBsv21Token`, `sendUtxos`, `createOrdListings`, `createOrdTokenListings`

Refer to the function documentation for a complete list of configuration options for each function.

### Broadcasting

```ts
import { oneSatBroadcaster } from "js-1sat-ord"

// ...

const { status, txid, message  } = await tx.broadcast(oneSatBroadcaster())
```

#### Using with Bundlers

Since this package depends on `@bsv/sdk` there should be no issue with bundlers.

## Resources

There is a public 1Sat API which is documented here:

<https://ordinals.gorillapool.io/api/docs>

***


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://js.1satordinals.com/readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.