ar.io Logoar.io Documentation
TurboPayment Service

Protected

Protected routes for inter-service communication (requires PRIVATE_ROUTE_SECRET)

Reserve user balance for data upload

PROTECTED ROUTE - Requires PRIVATE_ROUTE_SECRET authentication header.

Reserves Winston credits from a user's balance for an upcoming data upload. Called by the upload service before accepting a data item upload.

The reservation is temporary and will be:

  • Finalized (deducted) when upload completes successfully
  • Refunded if upload fails or is canceled

Authorization: x-auth-token header must match PRIVATE_ROUTE_SECRET environment variable.

GET
/reserve-balance/{token}/{signerAddress}

Path Parameters

tokenstring

Currently unused (kept for backward compatibility)

signerAddressstring

User's wallet address

Query Parameters

byteCountinteger

Number of bytes being uploaded

dataItemIdstring

Data item ID for the upload

paidBy?string

Comma-separated list of addresses paying (delegated payment)

paymentDirective?string

Payment directive (e.g., x402 payment ID)

ipBucket?string

The client's subnet bucket, forwarded by the upload service so the per-IP free-tier cap can be evaluated when committing a free grant.

Header Parameters

x-auth-tokenstring

Must match PRIVATE_ROUTE_SECRET

Response Body

curl -X GET "https://turbo.ardrive.io/v1/reserve-balance/arweave/string?byteCount=0&dataItemId=string&paidBy=string&paymentDirective=string&ipBucket=string" \  -H "x-auth-token: string"
"1000000"
"Invalid parameters"
"Invalid authorization token"
"Insufficient balance"
"User not found"
"Error reserving balance"

Refund previously reserved balance

PROTECTED ROUTE - Requires PRIVATE_ROUTE_SECRET authentication header.

Refunds Winston credits that were previously reserved for a data upload. Called by the upload service when an upload fails or is canceled.

Authorization: x-auth-token header must match PRIVATE_ROUTE_SECRET environment variable.

GET
/refund-balance/{token}/{signerAddress}

Path Parameters

tokenstring

Currently unused (kept for backward compatibility)

signerAddressstring

User's wallet address

Query Parameters

winstonCreditsstring

Winston amount to refund

dataItemIdstring

Data item ID for the failed/canceled upload

Header Parameters

x-auth-tokenstring

Must match PRIVATE_ROUTE_SECRET

Response Body

curl -X GET "https://turbo.ardrive.io/v1/refund-balance/arweave/string?winstonCredits=string&dataItemId=string" \  -H "x-auth-token: string"
"Balance refunded"
"Invalid parameters"
"Invalid authorization token"
"User not found"
"Error refunding balance"

Check if user has sufficient balance

PROTECTED ROUTE - Requires PRIVATE_ROUTE_SECRET authentication header.

Checks whether a user has sufficient Winston credits for a given byte count upload. Called by the upload service before accepting a data upload.

Authorization: x-auth-token header must match PRIVATE_ROUTE_SECRET environment variable.

GET
/check-balance/{token}/{signerAddress}

Path Parameters

tokenstring

Currently unused (kept for backward compatibility)

signerAddressstring

User's wallet address

Query Parameters

byteCountinteger

Number of bytes to check

paidBy?string

Comma-separated list of addresses paying (delegated payment)

ipBucket?string

The client's subnet bucket, forwarded by the upload service so the per-IP free-tier cap can be evaluated.

Header Parameters

x-auth-tokenstring

Must match PRIVATE_ROUTE_SECRET

Response Body

curl -X GET "https://turbo.ardrive.io/v1/check-balance/arweave/string?byteCount=0&paidBy=string&ipBucket=string" \  -H "x-auth-token: string"
{
  "userHasSufficientBalance": true,
  "bytesCostInWinc": "1000000",
  "userBalanceInWinc": "5000000",
  "freeGrant": true,
  "tier": "lifetime",
  "adjustments": [
    {
      "name": "Adjustment",
      "description": "Some great subsidy",
      "operatorMagnitude": "0.6",
      "operator": "multiply",
      "adjustmentAmount": "-12300",
      "promoCode": "SOME-GREAT-CODE"
    }
  ]
}
{
  "userHasSufficientBalance": true,
  "bytesCostInWinc": "1000000",
  "userBalanceInWinc": "5000000",
  "freeGrant": true,
  "tier": "lifetime",
  "adjustments": [
    {
      "name": "Adjustment",
      "description": "Some great subsidy",
      "operatorMagnitude": "0.6",
      "operator": "multiply",
      "adjustmentAmount": "-12300",
      "promoCode": "SOME-GREAT-CODE"
    }
  ]
}
"Invalid authorization token"
{
  "userHasSufficientBalance": true,
  "bytesCostInWinc": "1000000",
  "userBalanceInWinc": "5000000",
  "freeGrant": true,
  "tier": "lifetime",
  "adjustments": [
    {
      "name": "Adjustment",
      "description": "Some great subsidy",
      "operatorMagnitude": "0.6",
      "operator": "multiply",
      "adjustmentAmount": "-12300",
      "promoCode": "SOME-GREAT-CODE"
    }
  ]
}
{
  "userHasSufficientBalance": true,
  "bytesCostInWinc": "1000000",
  "userBalanceInWinc": "5000000",
  "freeGrant": true,
  "tier": "lifetime",
  "adjustments": [
    {
      "name": "Adjustment",
      "description": "Some great subsidy",
      "operatorMagnitude": "0.6",
      "operator": "multiply",
      "adjustmentAmount": "-12300",
      "promoCode": "SOME-GREAT-CODE"
    }
  ]
}
"Error checking balance"

Create delegated payment approval

PROTECTED ROUTE - Requires PRIVATE_ROUTE_SECRET authentication header.

Creates an approval allowing another address to spend credits from the paying address's balance. This enables delegated payment scenarios where one user pays for another user's uploads.

Authorization: x-auth-token header must match PRIVATE_ROUTE_SECRET environment variable.

GET
/account/approvals/create

Query Parameters

payingAddressstring

Address that will pay

approvedAddressstring

Address that is approved to spend

approvedWincAmountstring

Winston amount approved

approvalDataItemIdstring

Data item ID for the approval

expirationDatestring

When the approval expires

Formatdate-time

Header Parameters

x-auth-tokenstring

Must match PRIVATE_ROUTE_SECRET

Response Body

curl -X GET "https://turbo.ardrive.io/v1/account/approvals/create?payingAddress=string&approvedAddress=string&approvedWincAmount=string&approvalDataItemId=string&expirationDate=2019-08-24T14%3A15%3A22Z" \  -H "x-auth-token: string"
{}
"Invalid parameters"
"Invalid authorization token"
"Insufficient balance"
"Error creating approval"

Revoke delegated payment approvals

PROTECTED ROUTE - Requires PRIVATE_ROUTE_SECRET authentication header.

Revokes one or more delegated payment approvals, preventing the approved address from spending any more credits from the paying address.

Authorization: x-auth-token header must match PRIVATE_ROUTE_SECRET environment variable.

GET
/account/approvals/revoke

Query Parameters

payingAddressstring

Address that pays

approvedAddressstring

Address whose approval is being revoked

revokeDataItemIdstring

Data item ID for the revocation

Header Parameters

x-auth-tokenstring

Must match PRIVATE_ROUTE_SECRET

Response Body

curl -X GET "https://turbo.ardrive.io/v1/account/approvals/revoke?payingAddress=string&approvedAddress=string&revokeDataItemId=string" \  -H "x-auth-token: string"
[
  {}
]
"Invalid parameters"
"Invalid authorization token"
"Error revoking approvals"

How is this guide?

x402

Previous Page

Webhooks POST

Next Page