Uploading & Credits

Uploads go through the sandbox Turbo bundler. Data items are ANS-104 — use the Turbo SDK pointed at the sandbox endpoints, or POST a signed data item directly.

Uploading with the Turbo SDK

Point the SDK at the sandbox upload and payment services and sign with your devnet Solana keypair:

import { TurboFactory, HexSolanaSigner } from '@ardrive/turbo-sdk';
import bs58 from 'bs58';
import fs from 'node:fs';

const signer = new HexSolanaSigner(bs58.encode(secretKey)); // your devnet Solana keypair

const turbo = TurboFactory.authenticated({
  signer,
  token: 'solana',
  gatewayUrl: 'https://api.devnet.solana.com', // Solana RPC — used to VERIFY funding txs, NOT the ar.io gateway
  uploadServiceConfig:  { url: 'https://upload.services.ar-io.dev' },
  paymentServiceConfig: { url: 'https://payment.services.ar-io.dev' },
});

const { id, winc } = await turbo.uploadFile({
  fileStreamFactory: () => fs.createReadStream(path),
  fileSizeFactory:   () => size,
});

// Read the bytes back from the ar.io gateway, not from Turbo:
// https://ar-io.dev/raw/<id>

Raw POST

If you've already signed an ANS-104 data item, post the raw bytes:

POST https://upload.services.ar-io.dev/v1/tx
Content-Type: application/octet-stream

<raw data item bytes>

A 200 returns { id, winc, dataCaches, ... }. winc: "0" means the upload was free.

Limits & responses

• Hard max size: 10 MiB per data item. Larger uploads return 413 (Data item is too large…).
• Free tier (no payment required), far larger than mainnet's 105 KiB:
  • Up to 5 MiB per item is eligible to be free.
  • 100 MiB total free per wallet (lifetime) and 100 MiB per IP /24 subnet (lifetime): an upload must fit under both or it isn't free.
  • GET https://upload.services.ar-io.dev/info reports the current limits as freeTier.
  • Over the free allowance, or an item too big to be free, returns 402 { code: "FREE_TIER_EXHAUSTED", topUpUrl, byteCount } → top up credits.

Check your remaining free allowance

Before uploading, check how many free-tier bytes a wallet has left with GET /v1/account/free — no signature required, any wallet by address:

GET https://payment.services.ar-io.dev/v1/account/free?address=<native-address>

// bytesRemaining: null = unlimited (exempt wallet); 0 = free tier disabled
{ "bytesRemaining": 7340032 }

With the Turbo SDK:

const { bytesRemaining } = await turbo.getFreeStatus();            // your own wallet (authenticated)
const { bytesRemaining } = await turbo.getFreeStatus('<address>'); // any wallet (unauthenticated)

Or the CLI: turbo free-status --address <native-address>.

bytesRemaining is a wallet-side figure and advisory — the per-subnet cap and the authoritative free/charge decision are applied at upload time. Deployment-wide free-tier limits are reported by GET /v1/info.

Getting credits

Credits (Turbo "winc") are what the bundler debits for paid uploads and ArNS purchases. Fund them with testnet value only.

Accepted funding tokens:

Crypto top-up

Submit your funding transaction to POST /v1/account/balance/:token. Get the per-token receiving addresses from GET /v1/info (the addresses map). The transaction is verified on the testnet RPC for that token, then your balance is credited.

Stripe (test cards)

The fiat top-up flow runs in test mode. Use Stripe test cards — e.g. 4242 4242 4242 4242 with any future expiry and CVC. No real money moves.

x402 (USDC)

The unsigned x402 upload path runs on Base Sepolia testnet USDC: POST /x402/upload/unsigned, then pay the returned 402 quote via an X-PAYMENT header. See x402 uploading for the full flow.

Next steps