DALP token document upload flow for API integrations

Upload, confirm, list, download, and delete token or asset documents through the DALP API, SDK, and CLI.

DALP token document APIs manage files that belong to an asset, such as a prospectus, term sheet, regulatory filing, compliance report, certificate, reserve audit, or other asset evidence. The API uses the same two-step upload pattern as other document flows:

Request a presigned upload URL for a token document.
Upload the file directly to storage using the returned method and headers.
Confirm the upload so DALP records the document against the token.
List, download, or delete the document later through the token document API.

This flow is for token or asset documents. Use the KYC document upload guide when the file belongs to a user's KYC profile instead of an asset.

Endpoints

The token document API exposes these operations:

GET /api/v2/tokens/{tokenAddress}/documents lists token documents with pagination, sorting, and filtering.
POST /api/v2/tokens/{tokenAddress}/document-uploads returns a presigned upload URL.
POST /api/v2/tokens/{tokenAddress}/documents confirms an uploaded file and creates the document record.
POST /api/v2/tokens/{tokenAddress}/documents/{documentId}/downloads returns a secure download URL.
DELETE /api/v2/tokens/{tokenAddress}/documents/{documentId} deletes a token document.

Request an upload URL

Request an upload URL before sending the file bytes. The request describes the file and how it should be classified on the asset.

const upload = await client.token.documents.getUploadUrl({
  params: {
    tokenAddress: "0xTOKEN",
  },
  body: {
    documentType: "prospectus",
    fileName: "bond-prospectus.pdf",
    fileSize: 2_400_000,
    mimeType: "application/pdf",
    visibility: "public",
    title: "Bond prospectus",
    description: "Published prospectus for investor review",
  },
});

Supported MIME types are:

application/pdf
image/jpeg
image/png
image/webp
application/vnd.openxmlformats-officedocument.wordprocessingml.document
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

fileSize must be positive and no larger than 50 MiB.

Upload the file bytes

Upload the file directly to the returned URL. Use the returned method and headers. Some storage backends include provider-specific headers in the upload URL response.

await fetch(upload.data.uploadUrl, {
  method: upload.data.method,
  headers: upload.data.headers,
  body: fileBytes,
});

Do not replace the returned headers with only Content-Type. Provider-specific headers are part of the upload contract.

Confirm the uploaded document

After the file upload succeeds, confirm the upload with the returned objectKey. The confirmation creates the token document record and returns the stored document metadata.

const document = await client.token.documents.confirmUpload({
  params: {
    tokenAddress: "0xTOKEN",
  },
  body: {
    objectKey: upload.data.objectKey,
    documentType: "prospectus",
    fileName: "bond-prospectus.pdf",
    fileSize: 2_400_000,
    mimeType: "application/pdf",
    visibility: "public",
    title: "Bond prospectus",
    description: "Published prospectus for investor review",
  },
});

The response includes the document id, groupId, versionNumber, isLatest, fileHash, uploadedAt, and uploader metadata.

DALP calculates fileHash from the uploaded file bytes when the upload is confirmed. Store that value in downstream systems when you need to reconcile that an asset document record still points to the expected file.

Use replaceGroupId when a new upload should replace a previous document in the same document group. The new record becomes the latest version for that group.

Record document integrity claims

Token document upload records and asset-level claims serve different purposes:

The token document upload flow stores the file metadata, version group, and fileHash that belongs to the uploaded document record.
An asset-level document-hash claim can reference a SHA-256 hash, document type, and file name without placing the document contents on-chain.

Use the upload flow to manage access, download links, and document versions. Use an asset-level document-hash claim when an asset also needs an on-chain integrity reference for a specific document.

Choose document type and visibility

Document types include asset evidence such as:

prospectus
term_sheet
legal_opinion
regulatory_filing
compliance_report
annual_report
financial_statement
credit_rating
covenant_agreement
shareholder_agreement
fund_fact_sheet
subscription_agreement
nav_report
reserve_audit
attestation_report
reserve_composition
certificate
interest_schedule
property_deed
survey_report
appraisal
environmental_assessment
title_insurance
assay_certificate
storage_receipt
chain_of_custody
insurance_certificate
other

Visibility controls who can access the document:

public: visible to anyone who can access the token document surface.
holders: visible to token holders.
restricted: limited to explicitly allowed access paths.

Choose the narrowest visibility that fits the operating process and regulatory basis for the document.

List documents

Use the list endpoint to reconcile published documents or populate an asset document table.

curl --globoff "https://your-platform.example.com/api/v2/tokens/0xTOKEN/documents?page[limit]=50&sort=-uploadedAt" \
  -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx"

The list endpoint supports pagination, sorting, filtering, and facets. Sortable fields include fileName, documentType, visibility, fileSize, and uploadedAt. Filterable fields are fileName, documentType, visibility, mimeType, isLatest, fileSize, and uploadedAt.

Filter with the same collection filter shape used by the current list endpoints. For example, request the latest public prospectuses uploaded after a cutoff time:

curl --globoff "https://your-platform.example.com/api/v2/tokens/0xTOKEN/documents?filter[documentType][eq]=prospectus&filter[visibility][eq]=public&filter[uploadedAt][gte]=2026-01-01T00:00:00.000Z" \
  -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx"

The API only returns the latest non-deleted document records visible to the caller. Public documents are visible through the token document surface. Holder visibility requires a caller with an asset role, and restricted visibility requires governance or admin rights.

Download or delete a document

Request a secure download URL when a user needs to retrieve the file:

const download = await client.token.documents.getDownloadUrl({
  params: {
    tokenAddress: "0xTOKEN",
    documentId: document.data.id,
  },
});

Delete a document only when it should no longer be available from the asset's document record:

await client.token.documents.delete({
  params: {
    tokenAddress: "0xTOKEN",
    documentId: document.data.id,
  },
});

Keep the business reason and approval evidence for deletes in your operating records. The delete call removes the document record from the API surface; it is not a substitute for your regulated record-retention process.

CLI commands

The DALP CLI exposes the same token document lifecycle:

dalp tokens documents list 0xTOKEN

dalp tokens documents get-upload-url \
  --address 0xTOKEN \
  --fileName bond-prospectus.pdf \
  --fileSize 2400000 \
  --mimeType application/pdf \
  --documentType prospectus \
  --visibility public

dalp tokens documents confirm-upload \
  --address 0xTOKEN \
  --objectKey uploads/token-documents/example-object-key \
  --documentType prospectus \
  --fileName bond-prospectus.pdf \
  --fileSize 2400000 \
  --mimeType application/pdf \
  --visibility public

dalp tokens documents get-download-url \
  --address 0xTOKEN \
  --documentId doc_123

dalp tokens documents delete \
  --address 0xTOKEN \
  --documentId doc_123

Use the API or SDK for the direct file upload step because the CLI returns the presigned URL and object key; it does not upload the local file bytes for you.

Token document uploads