ar.io Logoar.io Documentation
TurboPayment Service

ArNS

Arweave Name System (ArNS) registration and management

Get price for ArNS name registration or operation

Returns the mARIO (AR.IO token) and Winston credit cost for an ArNS name operation.

Optionally includes a fiat currency estimate if the currency query parameter is provided.

Supported Intents:

  • buy-record: Purchase a new ArNS name
  • upgrade-name: Upgrade a lease to permabuy
  • extend-lease: Extend the lease duration
  • increase-undername-limit: Increase the number of permitted undernames
GET
/arns/price/{intent}/{name}

Path Parameters

intentstring

Intent for ArNS name operation

Value in"buy-record" | "upgrade-name" | "extend-lease" | "increase-undername-limit"
namestring

The ArNS name (without .ar suffix)

Query Parameters

currency?string

If provided, includes a fiat currency estimate in the response

years?integer

Number of years for lease (required for buy-record and extend-lease)

type?string

Type of name registration (required for buy-record)

Value in"lease" | "permabuy"
increaseQty?integer

Quantity to increase (required for increase-undername-limit)

processId?string

AR.IO process ID (optional)

Header Parameters

x-signature?string

The signature value derived from signing the request's data concatenated with the provided nonce using the private key from the provided public key

x-nonce?string

The nonce value concatenated with the request's data when deriving the provided the signature

x-public-key?string

The "modulus" of the JWK used to create the signature header

Response Body

curl -X GET "https://turbo.ardrive.io/v1/arns/price/buy-record/myname?currency=usd&years=1&type=lease&increaseQty=0&processId=string" \  -H "x-signature: string" \  -H "x-nonce: string" \  -H "x-public-key: string"
{
  "mARIO": "1000000",
  "winc": "974711979594",
  "antSpawnSurchargeWinc": "600000000000",
  "wincTotalWithAntSpawn": "1474711979594",
  "fiatEstimate": {
    "paymentAmount": 0,
    "paymentAmountWithAntSpawn": 0,
    "antSpawnSurchargeAmount": 0,
    "quotedPaymentAmount": 0,
    "excessWincAmount": "string",
    "adjustments": [
      {
        "name": "Adjustment",
        "description": "Some great subsidy",
        "operatorMagnitude": "0.6",
        "operator": "multiply",
        "adjustmentAmount": "-12300",
        "promoCode": "SOME-GREAT-CODE"
      }
    ],
    "fees": [
      {
        "name": "Adjustment",
        "description": "Some great subsidy",
        "operatorMagnitude": "0.6",
        "operator": "multiply",
        "adjustmentAmount": "-12300",
        "promoCode": "SOME-GREAT-CODE"
      }
    ]
  }
}
"Invalid ArNS name"
"Price Oracle Unavailable"

Get ArNS purchase status

Retrieves the status of an ArNS purchase transaction by its nonce (unique ID).

Use this endpoint to track the progress of a purchase initiated via POST /arns/purchase.

GET
/arns/purchase/{nonce}

Path Parameters

noncestring

The unique nonce returned when the purchase was initiated

Formatuuid

Response Body

curl -X GET "https://turbo.ardrive.io/v1/arns/purchase/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{
  "nonce": "550e8400-e29b-41d4-a716-446655440000",
  "name": "myname",
  "intent": "buy-record",
  "mARIOQty": "1000000",
  "wincQty": "5000000000",
  "owner": "abcdefghijklmnopqrxtuvwxyz123456789ABCDEFGH",
  "processId": "process123",
  "increaseQty": 0,
  "type": "lease",
  "years": 1,
  "messageId": "msg123",
  "status": "PENDING",
  "usdArRate": 5.42,
  "usdArioRate": 0.012
}
"Purchase status not found"
"Database unavailable"

Get Stripe payment quote for ArNS name purchase

Creates a Stripe payment session (checkout or payment intent) for purchasing an ArNS name with fiat currency.

This endpoint:

  1. Calculates the mARIO and Winston credit cost
  2. Converts to the requested fiat currency
  3. Creates a Stripe payment session
  4. Stores a quote in the database
  5. Returns both the quote and payment session

Payment Methods:

  • checkout-session: Full Stripe Checkout experience (redirects to Stripe)
  • payment-intent: Embedded payment flow (integrate in your UI)
GET
/arns/quote/{method}/{address}/{currency}/{intent}/{name}

Path Parameters

methodstring

Stripe payment method type

Value in"checkout-session" | "payment-intent"
addressstring

Destination Arweave address

currencystring

Currency type for a given payment amount

intentstring

Intent for ArNS name operation

Value in"buy-record" | "upgrade-name" | "extend-lease" | "increase-undername-limit"
namestring

The ArNS name (without .ar suffix)

Query Parameters

promoCode?string

Comma-separated list of promo codes

uiMode?string

Which UI Mode to create the checkout session in

Default"hosted"
returnUrl?string

The URL to return to after a successful payment

Default"https://app.example.com"
successUrl?string

The URL to return to after a successful payment

Default"https://app.example.com"
cancelUrl?string

The URL to return to after a canceled payment

Default"https://app.example.com"
years?integer
type?string

Type of ArNS name

Value in"lease" | "permabuy"
increaseQty?integer
processId?string

Header Parameters

x-signature?string

The signature value derived from signing the request's data concatenated with the provided nonce using the private key from the provided public key

x-nonce?string

The nonce value concatenated with the request's data when deriving the provided the signature

x-public-key?string

The "modulus" of the JWK used to create the signature header

Response Body

curl -X GET "https://turbo.ardrive.io/v1/arns/quote/checkout-session/string/usd/buy-record/string?promoCode=string&uiMode=embedded&returnUrl=https%3A%2F%2Fapp.example.com&successUrl=https%3A%2F%2Fapp.example.com&cancelUrl=https%3A%2F%2Fapp.example.com&years=0&type=lease&increaseQty=0&processId=string" \  -H "x-signature: string" \  -H "x-nonce: string" \  -H "x-public-key: string"
{
  "purchaseQuote": {
    "nonce": "f25f24f2-d581-4594-9824-123d5821fb65",
    "name": "string",
    "intent": "buy-record",
    "mARIOQty": "string",
    "wincQty": "string",
    "paymentAmount": 0,
    "quotedPaymentAmount": 0,
    "currencyType": "usd",
    "quoteExpirationDate": "2019-08-24T14:15:22Z",
    "paymentProvider": "stripe",
    "excessWincAmount": "string",
    "adjustments": [
      {
        "name": "Adjustment",
        "description": "Some great subsidy",
        "operatorMagnitude": "0.6",
        "operator": "multiply",
        "adjustmentAmount": "-12300",
        "promoCode": "SOME-GREAT-CODE"
      }
    ]
  },
  "paymentSession": {
    "id": "cs_test_a1lFM2vIpifSqH8VtIjnbSGnr0RAQtEx6R2OMbhvbeK7fradNG7357Roxy",
    "client_secret": "cs_test_a1lFM2vIpifSqH8VtIjnbSGnr0RAQtEx6R2OMbhvbeK7fradNG7357Roxy#fidkdWxOYHwnPyd1blpxYHZxWjA0T1BEcXJGPWR1VUpSbkFJbTdDVV9uVG5sTl9AblFqM3J0YklGcVRqRmlJM1YxaTdvaWdnZjBIYkphckpQYVA8UWs8NktLc3REQmdwNDQwaW5PRm1IbG5CNTVdUGNRaGo3fycpJ2N3amhWYHdzYHcnP3F3cGApJ2lkfGpwcVF8dWAnPyd2bGtiaWBabHFgaCcpJ2BrZGdpYFVpZGZgbWppYWB3dic%2FcXdwYHgl",
    "url": "https://checkout.stripe.com/c/pay/cs_test_a1lFM2vIpifSqH8VtIjnbSGnr0RAQtEx6R2OMbhvbeK7fradNG7357Roxy#fidkdWxOYHwnPyd1blpxYHZxWjA0T1BEcXJGPWR1VUpSbkFJbTdDVV9uVG5sTl9AblFqM3J0YklGcVRqRmlJM1YxaTdvaWdnZjBIYkphckpQYVA8UWs8NktLc3REQmdwNDQwaW5PRm1IbG5CNTVdUGNRaGo3fycpJ2N3amhWYHdzYHcnP3F3cGApJ2lkfGpwcVF8dWAnPyd2bGtiaWBabHFgaCcpJ2BrZGdpYFVpZGZgbWppYWB3dic%2FcXdwYHgl"
  },
  "adjustments": [
    {
      "name": "Adjustment",
      "description": "Some great subsidy",
      "operatorMagnitude": "0.6",
      "operator": "multiply",
      "adjustmentAmount": "-12300",
      "promoCode": "SOME-GREAT-CODE"
    }
  ],
  "fees": [
    {
      "name": "Adjustment",
      "description": "Some great subsidy",
      "operatorMagnitude": "0.6",
      "operator": "multiply",
      "adjustmentAmount": "-12300",
      "promoCode": "SOME-GREAT-CODE"
    }
  ]
}
"Invalid parameters"
"Stripe unavailable"

List the ArNS names a wallet bought through Turbo

Receipt history for a wallet — NOT an ownership oracle. A name that was transferred away keeps its receipt and still appears here, so read present control from the chain using the returned antId.

Open-by-address (no signature), mirroring /account/balance.

GET
/arns/my-names/{address}

Path Parameters

addressstring

The wallet's Turbo identity (native address).

Response Body

curl -X GET "https://turbo.ardrive.io/v1/arns/my-names/string"
{
  "names": [
    {
      "name": "string",
      "antId": "string",
      "intent": "string",
      "type": "lease",
      "years": 0,
      "purchaseDate": "2019-08-24T14:15:22Z",
      "custodial": true,
      "selfCustody": true
    }
  ]
}

Create an ArNS action

Creates and (where Turbo holds the authority) immediately performs an ArNS action. Debits credits once, at creation, for ALL twelve actions — no action is free. The four ARIO-spending actions (buy-name, extend-lease, upgrade-name, increase-undername-limit) recover their registration cost; the other eight recover a small margin against Turbo's sponsored gas/rent.

Authorization: payer signature always (x-signature / x-public-key / x-nonce). The five RECORD-SCOPED actions — set-record, remove-record, set-record-metadata, remove-record-metadata and transfer-record — additionally require the ANT owner's action-bound proof in the x-owner-* headers, verified against the ANT's CURRENT ON-CHAIN owner. The proof binds every field it carries, so a signature authorizing one set of metadata values does not authorize another.

set-record-metadata fields are tri-state: omit one to leave it unchanged, or send null to clear it. Those are bound distinctly, so "clear the description" and "set it to empty" are different messages.

The returned transaction carries a Solana blockhash that dies in ~60-90 seconds. Sign those exact bytes — never rebuild the message, or Turbo's fee-payer signature stops covering it.

POST
/arns/actions/{action}

Path Parameters

actionstring
Value in"buy-name" | "extend-lease" | "upgrade-name" | "increase-undername-limit" | "set-record" | "remove-record" | "add-controller" | "remove-controller" | "transfer" | "set-record-metadata" | "remove-record-metadata" | "transfer-record"

Query Parameters

name?string

ArNS name. Required for buy-name / extend-lease / upgrade-name / increase-undername-limit.

ownerAddress?string

The SOLANA address that owns (or will own) the ANT. NOT the wallet that signed the request. Required for every ANT-scoped action.

antId?string

Existing ANT. Required for every action except the four name actions.

target?string

transfer destination, or the controller for add/remove-controller (defaults to Turbo).

type?string
Value in"lease" | "permabuy"
years?integer
Range1 <= value <= 5
increaseQty?integer
Range1 <= value
undername?string
Lengthlength <= 61
transactionId?string
ttlSeconds?integer
Range60 <= value <= 86400
displayName?string

set-record-metadata. Tri-state — omit to leave unchanged, send null (JSON body) to CLEAR, or a value to set.

recordLogo?string

set-record-metadata. Tri-state, as displayName.

recordDescription?string

set-record-metadata. Tri-state, as displayName.

recordKeywords?string

set-record-metadata. Comma-separated in a query string, or a JSON array in a body. Tri-state, as displayName.

paidBy?string

Comma-separated addresses to charge instead of the signer, via a delegated-payment approval they granted. Accepted in the query string OR the JSON body — the turbo-sdk posts a bare path and puts every param, this one included, in the body.

Header Parameters

x-signaturestring

The signature value derived from signing the request's data concatenated with the provided nonce using the private key from the provided public key

x-public-keystring

The "modulus" of the JWK used to create the signature header

x-noncestring

The nonce value concatenated with the request's data when deriving the provided the signature

x-owner-signature?string

The five RECORD-SCOPED actions only — set-record, remove-record, set-record-metadata, remove-record-metadata and transfer-record. Ed25519 signature by the ANT's Solana key over ["arns", action, ...fields].join("\n") + the x-owner-nonce. Verified against the ANT's CURRENT on-chain owner.

x-owner-public-key?string
x-owner-nonce?string
x-owner-signature-type?integer

Signature type of the owner key (4 = Solana).

Request Body

Every parameter above may be sent as a JSON body instead of a query string; the body wins where both are present. antState is body-shaped and is the reason to prefer one — in a query string it must be a JSON-encoded string.

antState?ArNSBuyAntState

buy-name ONLY — the opening state of the ANT being minted. Identical in shape to @ar.io/sdk's ArNSBuyAntState, which a browser passes to buyRecord({ antState }) when it settles in ARIO directly, so a client sends the same object whichever way the customer pays.

FREE and ATOMIC: these values are written by the same ario_ant::initialize the customer already signs, which always writes the root @ record — without antState it points at the AR.IO logo TX. So this replaces a default rather than adding work: no second action, no second signature, no second debit, and the customer's signature covers it (which is why no owner proof is required or taken).

⚠️ SIZE BUDGET. The sponsored spawn is ONE Solana transaction against the 1232-byte packet limit, and it also carries Turbo's SOL transfer and the add_controller grant. With a worst-case 51-character name only ~71 bytes are spare: transactionId + targetProtocol cost ~1 byte (the target REPLACES a 43-char default), ticker and logo fit, and description/keywords at their on-chain maxima do NOT. Over-limit is a 400 naming the fix, raised before the transaction is handed over and with the debit refunded — never a chain failure. A shorter name buys headroom back, so there is no fixed per-field cap: the service measures the real transaction.

Sending antState on any action other than buy-name is a 400, as is sending a TOP-LEVEL transactionId on buy-name (that spelling means the set-record target; silently ignoring it would leave the name pointing at the AR.IO logo).

paidBy?string

As the query parameter of the same name. Also accepted as a JSON array.

Response Body

curl -X POST "https://turbo.ardrive.io/v1/arns/actions/buy-name?name=string&ownerAddress=string&antId=string&target=string&type=lease&years=1&increaseQty=1&undername=string&transactionId=string&ttlSeconds=60&displayName=string&recordLogo=string&recordDescription=string&recordKeywords=string&paidBy=string" \  -H "x-signature: string" \  -H "x-public-key: string" \  -H "x-nonce: string" \  -H "x-owner-signature: string" \  -H "x-owner-public-key: string" \  -H "x-owner-nonce: string" \  -H "x-owner-signature-type: 4" \  -H "Content-Type: application/json" \  -d '{}'
{
  "nonce": "f25f24f2-d581-4594-9824-123d5821fb65",
  "action": "string",
  "status": "completed",
  "antId": "string",
  "messageId": "string",
  "wincQty": "string",
  "alreadyCompleted": true
}
Empty
Empty
Empty
Empty

Price an ArNS action before creating it

Preview the winc a POST /arns/actions/{action} call for this SAME action will debit, without creating (or being charged for) one. Covers only the eight non-purchase actions (set-record, remove-record, set-record-metadata, remove-record-metadata, transfer-record, add-controller, remove-controller, transfer) — the four ARIO-purchase actions (buy-name, extend-lease, upgrade-name, increase-undername-limit) are priced by GET /arns/price/{intent}/{name} instead, since their price depends on name/type/years/increaseQty, which this route never asks for.

Both routes read the SAME pricing resolver the actual debit uses, so a quote here cannot drift from what create actually charges.

No signature required. The amount has no user-specific component — it depends only on the action and live SOL/AR rates, not on who is asking. Same 404-avoiding, "a read costs nothing" reasoning as GET /arns/purchase/{nonce}.

GET
/arns/actions/{action}/price

Path Parameters

actionstring
Value in"set-record" | "remove-record" | "set-record-metadata" | "remove-record-metadata" | "transfer-record" | "add-controller" | "remove-controller" | "transfer"

Response Body

curl -X GET "https://turbo.ardrive.io/v1/arns/actions/set-record/price"
{
  "action": "string",
  "wincQty": "string"
}
Empty
Empty

Submit the owner-signed transaction for an action

One submit path for every action. Takes the base64 transaction returned by the create call, now carrying the ANT owner's signature.

No payer auth. The authorization is the owner's signature inside the transaction, which the chain enforces against those exact instructions; the nonce is a random UUID capability. Requiring a second off-chain signature would break flows where the signer is not the payer.

Idempotent. A replay of a completed action returns its envelope with alreadyCompleted: true and performs no second purchase.

POST
/arns/actions/{nonce}/sign

Path Parameters

noncestring
Formatuuid

Request Body

transactionstring

Base64 wire transaction from the create call, signed by the ANT owner.

Response Body

curl -X POST "https://turbo.ardrive.io/v1/arns/actions/497f6eca-6276-4993-bfeb-53cbbbba6f08/sign" \  -H "Content-Type: application/json" \  -d '{    "transaction": "string"  }'
{
  "nonce": "f25f24f2-d581-4594-9824-123d5821fb65",
  "action": "string",
  "status": "completed",
  "antId": "string",
  "messageId": "string",
  "wincQty": "string",
  "alreadyCompleted": true
}
Empty
Empty

ArNS action status

Open by nonce (a random UUID handed only to the caller who created the action). Deliberately does NOT echo the transaction bytes.

GET
/arns/actions/{nonce}

Path Parameters

noncestring
Formatuuid

Response Body

curl -X GET "https://turbo.ardrive.io/v1/arns/actions/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{
  "nonce": "string",
  "action": "string",
  "status": "awaiting-signature",
  "antId": "string",
  "name": "string",
  "ownerAddress": "string",
  "paidBy": "string",
  "messageId": "string",
  "wincQty": "string",
  "expiresAt": "2019-08-24T14:15:22Z",
  "createdDate": "2019-08-24T14:15:22Z"
}
Empty

How is this guide?

Redemption GET

Previous Page

x402

Next Page