> For the complete documentation index, see [llms.txt](https://docs.radfi.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.radfi.co/dev/api-endpoints/etch.md).

# Etch

## POST /api/etch/validate/etch-rune

> Validate rune name uniqueness & block-height availability

```json
{"openapi":"3.0.0","info":{"title":"Radfi API","version":"1.0"},"servers":[{"url":"https://api.radfi.co","description":"Production"}],"paths":{"/api/etch/validate/etch-rune":{"post":{"operationId":"EtchController_validateEtchRune","summary":"Validate rune name uniqueness & block-height availability","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateEtchRuneDto"}}}},"responses":{"200":{"description":"result: already_etched | height_not_reach | ok (HTTP 503 when rune availability cannot be verified — all providers unreachable)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponseDto"}}}}},"tags":["etch"]}}},"components":{"schemas":{"ValidateEtchRuneDto":{"type":"object","properties":{"rune":{"type":"string","description":"Rune name with or without spacers (•)"}},"required":["rune"]},"BaseResponseDto":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"data":{"type":"object"},"metaData":{"$ref":"#/components/schemas/ResponseMetaData"}},"required":["code","message","data","metaData"]},"ResponseMetaData":{"type":"object","properties":{"totalItems":{"type":"number"},"currentPage":{"type":"number"},"pageSize":{"type":"number"},"totalPages":{"type":"number"}},"required":["totalItems","currentPage","pageSize","totalPages"]}}}}
```

## POST /api/etch/get-etch-address

> Get etch address and fee

```json
{"openapi":"3.0.0","info":{"title":"Radfi API","version":"1.0"},"servers":[{"url":"https://api.radfi.co","description":"Production"}],"paths":{"/api/etch/get-etch-address":{"post":{"operationId":"EtchController_getEtchAddress","summary":"Get etch address and fee","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FetchEtchAddressDto"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponseDto"}}}}},"tags":["etch"]}}},"components":{"schemas":{"FetchEtchAddressDto":{"type":"object","properties":{"runeName":{"type":"string"},"inscriptionType":{"type":"string"},"inscriptionContent":{"type":"string"}},"required":["runeName","inscriptionType","inscriptionContent"]},"BaseResponseDto":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"data":{"type":"object"},"metaData":{"$ref":"#/components/schemas/ResponseMetaData"}},"required":["code","message","data","metaData"]},"ResponseMetaData":{"type":"object","properties":{"totalItems":{"type":"number"},"currentPage":{"type":"number"},"pageSize":{"type":"number"},"totalPages":{"type":"number"}},"required":["totalItems","currentPage","pageSize","totalPages"]}}}}
```

## GET /api/etch/runes/details

> Get etch rune by id

```json
{"openapi":"3.0.0","info":{"title":"Radfi API","version":"1.0"},"servers":[{"url":"https://api.radfi.co","description":"Production"}],"paths":{"/api/etch/runes/details":{"get":{"operationId":"EtchController_getEtchedRune","summary":"Get etch rune by id","parameters":[{"name":"select","required":false,"in":"query","description":"Fields to select (comma separated). Use + prefix to include hidden fields. Example: name,status,+holders","schema":{"type":"string"}},{"name":"populate","required":false,"in":"query","description":"Relations to populate (comma separated). Example: wallet,token","schema":{"type":"string"}},{"name":"sort","required":false,"in":"query","description":"Sort field and order. Use - prefix for descending. Example: -createdAt","schema":{"type":"string"}}],"responses":{"200":{"description":"etch rune","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponseDto"}}}}},"tags":["etch"]}}},"components":{"schemas":{"BaseResponseDto":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"data":{"type":"object"},"metaData":{"$ref":"#/components/schemas/ResponseMetaData"}},"required":["code","message","data","metaData"]},"ResponseMetaData":{"type":"object","properties":{"totalItems":{"type":"number"},"currentPage":{"type":"number"},"pageSize":{"type":"number"},"totalPages":{"type":"number"}},"required":["totalItems","currentPage","pageSize","totalPages"]}}}}
```

## GET /api/etch/runes

> Get etched runes

```json
{"openapi":"3.0.0","info":{"title":"Radfi API","version":"1.0"},"servers":[{"url":"https://api.radfi.co","description":"Production"}],"paths":{"/api/etch/runes":{"get":{"operationId":"EtchController_getEtchedRunes","summary":"Get etched runes","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (default: 1)","schema":{"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Number of items per page (default: 10)","schema":{"type":"number"}},{"name":"sort","required":false,"in":"query","description":"Sort field and order. Use - prefix for descending. Example: -createdAt, createdAt","schema":{"type":"string"}},{"name":"select","required":false,"in":"query","description":"Fields to select (comma separated). Use + prefix to include hidden fields. Example: name,status,+holders","schema":{"type":"string"}},{"name":"populate","required":false,"in":"query","description":"Relations to populate (comma separated). Example: wallet,token","schema":{"type":"string"}}],"responses":{"200":{"description":"etched runes","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponseDto"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EtchEntity"}}}}]}}}}},"tags":["etch"]}}},"components":{"schemas":{"BaseResponseDto":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"data":{"type":"object"},"metaData":{"$ref":"#/components/schemas/ResponseMetaData"}},"required":["code","message","data","metaData"]},"ResponseMetaData":{"type":"object","properties":{"totalItems":{"type":"number"},"currentPage":{"type":"number"},"pageSize":{"type":"number"},"totalPages":{"type":"number"}},"required":["totalItems","currentPage","pageSize","totalPages"]},"EtchEntity":{"type":"object","properties":{}}}}}
```

## POST /api/etch/commit-tx

>

```json
{"openapi":"3.0.0","info":{"title":"Radfi API","version":"1.0"},"servers":[{"url":"https://api.radfi.co","description":"Production"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"EtchBuildCommitTxDto":{"type":"object","properties":{"runeName":{"type":"string"},"inscriptionType":{"type":"string"},"inscriptionContent":{"type":"string"},"userAddress":{"type":"string"},"feeTier":{"type":"number","description":"Fee tier for the pool (5000 = 0.5%, 10000 = 1%, 20000 = 2%, etc.)","minimum":5000,"maximum":100000},"diamondHandRewardRate":{"type":"number","description":"Diamond hands share of the available 66.67% (0-1, e.g., 0.5 = 50% of 66.67% = 33.33% total)","minimum":0,"maximum":1},"blockWithdrawals":{"type":"boolean","description":"Block withdrawals of this token from radFi (only internal transfers allowed)","default":false},"addLpSatsRate":{"type":"number","description":"Percentage of raised funds to allocate to liquidity (0-1, e.g., 0.2 = 20% to LP, 80% to creator)","minimum":0,"maximum":1},"customFeeRate":{"type":"number","description":"Customized fee rate for the etching transaction (>=1)","minimum":1},"isReserve":{"type":"boolean","description":"Reserve to launch the token at a later date","default":false},"userPremineAmount":{"type":"string","description":"Raw rune amount (base units) to transfer to the creator before public distribution. Must fit within the total premine supply."}},"required":["runeName","inscriptionType","inscriptionContent","userAddress","feeTier"]}}},"paths":{"/api/etch/commit-tx":{"post":{"operationId":"EtchController_buildCommitTx","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EtchBuildCommitTxDto"}}}},"responses":{"201":{"description":""}},"tags":["etch"]}}}}
```

## POST /api/etch/submit-etching

>

```json
{"openapi":"3.0.0","info":{"title":"Radfi API","version":"1.0"},"servers":[{"url":"https://api.radfi.co","description":"Production"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"SubmitEtchDto":{"type":"object","properties":{"signedBase64Psbt":{"type":"string"},"runeName":{"type":"string"},"inscriptionType":{"type":"string"},"inscriptionContent":{"type":"string"},"symbol":{"type":"string"},"creator":{"type":"string"},"description":{"type":"string"},"displayTicker":{"type":"string"},"social":{"$ref":"#/components/schemas/EtchSocialDto"}},"required":["signedBase64Psbt","runeName","inscriptionType","inscriptionContent","symbol","creator","description"]},"EtchSocialDto":{"type":"object","properties":{"x":{"type":"string"},"telegram":{"type":"string"},"website":{"type":"string"}}}}},"paths":{"/api/etch/submit-etching":{"post":{"operationId":"EtchController_submitEtch","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitEtchDto"}}}},"responses":{"201":{"description":""}},"tags":["etch"]}}}}
```

## GET /api/etch/top-holders

>

```json
{"openapi":"3.0.0","info":{"title":"Radfi API","version":"1.0"},"servers":[{"url":"https://api.radfi.co","description":"Production"}],"paths":{"/api/etch/top-holders":{"get":{"operationId":"EtchController_getTopHolders","parameters":[{"name":"runeId_eq","required":false,"in":"query","schema":{"type":"string"}},{"name":"balance_gte","required":false,"in":"query","schema":{"type":"number"}},{"name":"page","required":false,"in":"query","schema":{"type":"number"}},{"name":"pageSize","required":false,"in":"query","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"tags":["etch"]}}}}
```

## POST /api/etch/build-get-reward-tx

>

```json
{"openapi":"3.0.0","info":{"title":"Radfi API","version":"1.0"},"servers":[{"url":"https://api.radfi.co","description":"Production"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"EtchBuildGetRewardDto":{"type":"object","properties":{"runeId":{"type":"string"},"userAddress":{"type":"string"}},"required":["runeId","userAddress"]}}},"paths":{"/api/etch/build-get-reward-tx":{"post":{"operationId":"EtchController_buildGetRewardTx","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EtchBuildGetRewardDto"}}}},"responses":{"201":{"description":""}},"tags":["etch"]}}}}
```

## POST /api/etch/sign-reward-tx

>

```json
{"openapi":"3.0.0","info":{"title":"Radfi API","version":"1.0"},"servers":[{"url":"https://api.radfi.co","description":"Production"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"EtchSignAndBroadcastRewardTxDto":{"type":"object","properties":{"signedBase64Tx":{"type":"string"},"userAddress":{"type":"string"}},"required":["signedBase64Tx","userAddress"]}}},"paths":{"/api/etch/sign-reward-tx":{"post":{"operationId":"EtchController_signRewardTx","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EtchSignAndBroadcastRewardTxDto"}}}},"responses":{"201":{"description":""}},"tags":["etch"]}}}}
```

## GET /api/etch/rewards-amount

>

```json
{"openapi":"3.0.0","info":{"title":"Radfi API","version":"1.0"},"servers":[{"url":"https://api.radfi.co","description":"Production"}],"paths":{"/api/etch/rewards-amount":{"get":{"operationId":"EtchController_getRewardsAmount","parameters":[{"name":"userAddress","required":true,"in":"query","schema":{"type":"string"}},{"name":"runeIds","required":true,"in":"query","description":"separated by comma","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["etch"]}}}}
```

## POST /api/etch/open-mint

>

```json
{"openapi":"3.0.0","info":{"title":"Radfi API","version":"1.0"},"servers":[{"url":"https://api.radfi.co","description":"Production"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"EtchBuildOpenMintDto":{"type":"object","properties":{"runeId":{"type":"string"},"userAddress":{"type":"string"}},"required":["runeId"]}}},"paths":{"/api/etch/open-mint":{"post":{"operationId":"EtchController_openMint","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EtchBuildOpenMintDto"}}}},"responses":{"201":{"description":""}},"tags":["etch"]}}}}
```