Download

Downloading an asset means ordering one of its services and then fetching the data through a one-time URL.

The short version

const { url } = await nautilus.access({ assetDid: 'did:ope:1234abcd...' }) 
 
const response = await fetch(url)
const data = await response.text()

One call covers everything: satisfying any credential policy, asking the node for provider fees, reusing or placing an order, and building the URL.

Credentials are resolved before anything is ordered, so a policy you cannot satisfy costs nothing.

What you get back

const { url, transferTxId, reusedOrder, serviceId } = await nautilus.access({
  assetDid: 'did:ope:1234abcd...'
})

reusedOrder is worth checking: true means no datatoken was bought, because an order from a previous access was still inside the service's timeout. That is the difference between a free download and a paid one. The node does not report that order, so nautilus finds it in the datatoken's events; see the order on chain.

Choosing a service

An asset can offer several services. By default nautilus takes the first access service; name one explicitly when there is more than one. access() downloads from access services only and refuses a compute service before calling the node: run a job on it with compute() or freeCompute().

const asset = await nautilus.getAsset('did:ope:1234abcd...')
 
const services = getServices(asset) 
 
const { url } = await nautilus.access({
  assetDid: asset.id,
  serviceId: services[0].id 
})

Read the asset through the exported helpers — getServices, getMetadata and friends — rather than indexing into credentialSubject. They go through a version-aware manager, so your code survives a future DDO version moving fields.

Consumer parameters

If a service declares consumer parameters, pass values through userdata:

const { url } = await nautilus.access({
  assetDid: 'did:ope:1234abcd...',
  userdata: { 
    region: 'eu', 
    limit: 1000
  } 
})

The values are checked against the service's declaration before anything is sent: a missing required parameter, a value of the wrong type, a select value outside its options (or for a select that declares none) or an undeclared key throws a ConsumerParameterError. Keys set to undefined or null are left out of the download URL, and the rest is encoded as one query parameter, so values holding &, #, + or = reach the node intact. See validation, and the ConsumerParameterBuilder for the publishing side.

Selecting a file

A service can serve several files. fileIndex defaults to 0:

const { url } = await nautilus.access({
  assetDid: 'did:ope:1234abcd...',
  fileIndex: 1
})

Credential-gated assets

If the service requires a verifiable credential, configure a credential provider on the instance and nothing changes here — nautilus resolves the policy before ordering, so a policy you cannot satisfy costs nothing. See Credential-gated assets.

What it costs

Pricing is read from chain rather than from a subgraph, which v1 depended on and the current stack no longer runs. To inspect a price before committing:

const asset = await nautilus.getAsset('did:ope:1234abcd...')
const serviceId = getServices(asset)[0].id
const datatoken = getDatatokenForService(asset, serviceId) as string
 
const pricing = await getPricingInfo( 
  nautilus.getSigner(), 
  datatoken, 
  nautilus.getOceanConfig() 
) 
 
const price = await getOrderPrice(
  nautilus.getSigner(),
  pricing,
  nautilus.getOceanConfig()
)
 
console.log(pricing.schema, price.total)

pricing.schema is 'fixed', 'free', or 'none' when the datatoken has neither a fixed-rate exchange nor a dispenser and so cannot be ordered at all.

On top of the price, the order pays the provider fee the service's node asks for. That node is the service's serviceEndpoint, which the publisher chooses, so nautilus pays a non-zero fee only within the maxProviderFee you set, or with your confirmProviderFees callback. See what the node charges on top.

Try it

Runnable versions of everything on this page live in examples/:

npm start -- access:price did:ope:…      # what it costs, before you buy
npm start -- access:download did:ope:…   # order and fetch
npm start -- access:service did:ope:…    # pick a specific service
npm start -- access:userdata did:ope:…   # pass consumer parameters