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": "5000000000",
  "fiatEstimate": {
    "paymentAmount": 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"

Initiate ArNS name purchase using account balance

Initiates an ArNS name purchase transaction using the user's Winston credit balance.

This deducts credits from the user's account and submits the transaction to the AR.IO network.

Requirements:

  • User must have sufficient balance to cover the mARIO cost
  • Name must be available (checked by AR.IO network)
  • All required parameters must be provided based on the intent
POST
/arns/purchase/{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

ownerstring

Arweave address that will own the name

years?integer

Number of years (required for lease purchases)

type?string

Name type (required for buy-record)

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

Increase quantity (required for increase-undername-limit)

processId?string

AR.IO process ID

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-noncestring

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

x-public-keystring

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

Response Body

curl -X POST "https://turbo.ardrive.io/v1/arns/purchase/buy-record/string?owner=string&years=0&type=lease&increaseQty=0&processId=string" \  -H "x-signature: string" \  -H "x-nonce: string" \  -H "x-public-key: string"
{
  "purchaseReceipt": {
    "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
  },
  "arioWriteResult": {
    "id": "msg123"
  }
}
"Invalid parameters"
"Invalid signature"
"Insufficient balance"
"AR.IO network 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"

Transfer a custodied ArNS ANT out of Turbo custody

Self-custody exit: a credit-authenticated owner moves a Turbo-custodied ANT to a Solana pubkey they designate. Turbo (the on-chain owner) signs the transfer.

Authorization: action-bound, single-use signature over ("arns", "transfer", antId, target) + nonce. Requires x-signature, x-public-key and x-nonce headers.

POST
/arns/transfer/{antId}

Path Parameters

antIdstring

The ANT (Arweave Name Token) process id held in Turbo custody.

Query Parameters

targetstring

The Solana address to receive on-chain ownership of the ANT.

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-signature-type?integer

ANS-104 signature type of the signer (defaults to 1, Arweave).

Response Body

curl -X POST "https://turbo.ardrive.io/v1/arns/transfer/string?target=string" \  -H "x-signature: string" \  -H "x-public-key: string" \  -H "x-nonce: string" \  -H "x-signature-type: 1"
{
  "antId": "string",
  "target": "string",
  "owner": "string",
  "name": "string",
  "messageId": "string",
  "confirmed": true
}
"Missing or invalid target: must be a Solana address"
"Invalid or unbound signature for this action"
"ANT not found in your Turbo custody"
"Internal server error"

Set a resolution record on a custodied ArNS ANT

Turbo (the on-chain owner) writes a resolution record on the credit-authenticated user's behalf. undername defaults to "@" (the base name record).

Authorization: action-bound, single-use signature over ("arns", "set-record", antId, undername, transactionId, ttlSeconds) + nonce. Requires x-signature, x-public-key and x-nonce headers.

POST
/arns/manage/{antId}/set-record

Path Parameters

antIdstring

The ANT process id held in Turbo custody.

Query Parameters

undername?string

The record undername. "@" (the base record) or up to 61 chars of [a-zA-Z0-9_-]. Defaults to "@".

transactionIdstring

The Arweave transaction id the record should resolve to.

ttlSecondsinteger

Record TTL in seconds. Bounded by ARNS_MIN_TTL_SECONDS (default 60) and ARNS_MAX_TTL_SECONDS (default 86400).

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-signature-type?integer

ANS-104 signature type of the signer (defaults to 1, Arweave).

Response Body

curl -X POST "https://turbo.ardrive.io/v1/arns/manage/string/set-record?undername=%40&transactionId=QpmY8mZmFEC8RxNsgbxSV6e36OF6quIYaPRKzvUco0o&ttlSeconds=3600" \  -H "x-signature: string" \  -H "x-public-key: string" \  -H "x-nonce: string" \  -H "x-signature-type: 1"
{
  "antId": "string",
  "undername": "string",
  "transactionId": "string",
  "ttlSeconds": 0,
  "messageId": "string"
}
"Invalid transactionId: must be an Arweave transaction id"
"Invalid or unbound signature for this action"
"ANT not found in your Turbo custody"
"Internal server error"

Remove a resolution record (undername) from a custodied ArNS ANT

Turbo (the on-chain owner) removes a resolution record on the credit-authenticated user's behalf.

Authorization: action-bound, single-use signature over ("arns", "remove-record", antId, undername) + nonce. Requires x-signature, x-public-key and x-nonce headers.

POST
/arns/manage/{antId}/remove-record

Path Parameters

antIdstring

The ANT process id held in Turbo custody.

Query Parameters

undernamestring

The record undername to remove. "@" (base record) or up to 61 chars of [a-zA-Z0-9_-].

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-signature-type?integer

ANS-104 signature type of the signer (defaults to 1, Arweave).

Response Body

curl -X POST "https://turbo.ardrive.io/v1/arns/manage/string/remove-record?undername=blog" \  -H "x-signature: string" \  -H "x-public-key: string" \  -H "x-nonce: string" \  -H "x-signature-type: 1"
{
  "antId": "string",
  "undername": "string",
  "messageId": "string"
}
"Missing or invalid required parameter: undername"
"Invalid or unbound signature for this action"
"ANT not found in your Turbo custody"
"Internal server error"

How is this guide?

Redemption GET

Previous Page

x402

Next Page