Bundles - Octav Developer Docs

Group addresses into named bundles — the same bundles you see in Octav Pro.

Cost: 1 credit per call

Every address in a bundle must already be in your address book.

Interactive Playground: Test these endpoints in the API Playground. Get your API key at data.octav.fi

The bundle object

string

Bundle identifier.

string

Bundle name.

array

Addresses in the bundle.

{
  "id": "7714a4a5-487b-4b36-99ba-537e9cca8e62",
  "name": "Client A",
  "addresses": [
    "0xe760ad8df0a54aafd95e3bc271b65d224abeaa57",
    "0x05d2e386525b0495e952f6945d0fa2480ed5b056"
  ]
}

Bundles created through the API are private. Sharing settings are managed in Octav Pro.

List Bundles

Endpoint

GET https://api.octav.fi/v1/bundles

Example

curl "https://api.octav.fi/v1/bundles" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('https://api.octav.fi/v1/bundles', {
  headers: { 'Authorization': `Bearer ${apiKey}` }
});

const { data } = await response.json();

Example Response

{
  "data": [
    {
      "id": "7714a4a5-487b-4b36-99ba-537e9cca8e62",
      "name": "Client A",
      "addresses": ["0xe760ad8df0a54aafd95e3bc271b65d224abeaa57"]
    }
  ]
}

Create Bundle

Endpoint

POST https://api.octav.fi/v1/bundles

Parameters

string

required

1–255 characters. Must be unique.

array

required

1–100 addresses per request, each already in your address book. A bundle holds up to 10.

Example

curl -X POST "https://api.octav.fi/v1/bundles" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Client A",
    "addresses": ["0xe760ad8df0a54aafd95e3bc271b65d224abeaa57"]
  }'

const response = await fetch('https://api.octav.fi/v1/bundles', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Client A',
    addresses: ['0xe760ad8df0a54aafd95e3bc271b65d224abeaa57']
  })
});

const { data } = await response.json();

Response

201 with the new bundle.

Get Bundle

Endpoint

GET https://api.octav.fi/v1/bundles/{bundleId}

Parameters

string

required

Bundle identifier.

Example

curl "https://api.octav.fi/v1/bundles/7714a4a5-487b-4b36-99ba-537e9cca8e62" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  `https://api.octav.fi/v1/bundles/${bundleId}`,
  { headers: { 'Authorization': `Bearer ${apiKey}` } }
);

const { data } = await response.json();

Rename Bundle

Endpoint

PATCH https://api.octav.fi/v1/bundles/{bundleId}

Parameters

string

required

Bundle identifier.

string

required

1–255 characters. Must be unique.

Example

curl -X PATCH "https://api.octav.fi/v1/bundles/7714a4a5-487b-4b36-99ba-537e9cca8e62" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Client A — Q1" }'

const response = await fetch(
  `https://api.octav.fi/v1/bundles/${bundleId}`,
  {
    method: 'PATCH',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name: 'Client A — Q1' })
  }
);

const { data } = await response.json();

Delete Bundle

Endpoint

DELETE https://api.octav.fi/v1/bundles/{bundleId}

Parameters

string

required

Bundle identifier.

Example

curl -X DELETE "https://api.octav.fi/v1/bundles/7714a4a5-487b-4b36-99ba-537e9cca8e62" \
  -H "Authorization: Bearer YOUR_API_KEY"

await fetch(`https://api.octav.fi/v1/bundles/${bundleId}`, {
  method: 'DELETE',
  headers: { 'Authorization': `Bearer ${apiKey}` }
});

Response

204 with no body. The addresses stay in your address book.

Add Address to Bundle

Endpoint

POST https://api.octav.fi/v1/bundles/{bundleId}/addresses

Parameters

string

required

Bundle identifier.

string

required

Wallet address, already in your address book.

Example

curl -X POST "https://api.octav.fi/v1/bundles/7714a4a5-487b-4b36-99ba-537e9cca8e62/addresses" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "address": "0x05d2e386525b0495e952f6945d0fa2480ed5b056" }'

const response = await fetch(
  `https://api.octav.fi/v1/bundles/${bundleId}/addresses`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ address: '0x05d2e386525b0495e952f6945d0fa2480ed5b056' })
  }
);

const { data } = await response.json();

Response

Returns the updated bundle.

Remove Address from Bundle

Endpoint

DELETE https://api.octav.fi/v1/bundles/{bundleId}/addresses/{address}

Parameters

string

required

Bundle identifier.

string

required

Wallet address.

Example

curl -X DELETE "https://api.octav.fi/v1/bundles/7714a4a5-487b-4b36-99ba-537e9cca8e62/addresses/0x05d2e386525b0495e952f6945d0fa2480ed5b056" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  `https://api.octav.fi/v1/bundles/${bundleId}/addresses/${address}`,
  { method: 'DELETE', headers: { 'Authorization': `Bearer ${apiKey}` } }
);

const { data } = await response.json();

Response

Returns the updated bundle with 200. Removing the last member returns 422 — delete the bundle instead.

Limits

Limit	Default
Bundles	5
Addresses per bundle	10

Contact us to raise these. Bundle names must be unique and match case-sensitively. Two bundles cannot hold exactly the same addresses.

Error Responses

Code	Status	Meaning
`VALIDATION_ERROR`	400	Invalid or duplicate address
`BUNDLE_NOT_FOUND`	404	No such bundle
`BUNDLE_NAME_TAKEN`	409	Name already used
`BUNDLE_MEMBERS_ALREADY_BUNDLED`	409	Another bundle holds these addresses
`BUNDLE_QUOTA_REACHED`	422	Bundle limit reached
`BUNDLE_SIZE_LIMIT_EXCEEDED`	422	Address limit reached
`BUNDLE_EMPTY`	422	A bundle cannot be empty
`BUNDLE_ADDRESS_NOT_IN_ADDRESS_BOOK`	422	Address is not in your address book
`INTERNAL_ERROR`	500	Unexpected failure

{
  "error": {
    "code": "BUNDLE_ADDRESS_NOT_IN_ADDRESS_BOOK",
    "message": "Not in the address book: 0x05d2e386...",
    "addresses": ["0x05d2e386525b0495e952f6945d0fa2480ed5b056"]
  }
}

Rate limit: 360 requests/min.

Address Book

Manage saved addresses

Portfolio

Holdings for an address

​The bundle object

​List Bundles

​Endpoint

​Example

​Example Response

​Create Bundle

​Endpoint

​Parameters

​Example

​Response

​Get Bundle

​Endpoint

​Parameters

​Example

​Rename Bundle

​Endpoint

​Parameters

​Example

​Delete Bundle

​Endpoint

​Parameters

​Example

​Response

​Add Address to Bundle

​Endpoint

​Parameters

​Example

​Response

​Remove Address from Bundle

​Endpoint

​Parameters

​Example

​Response

​Limits

​Error Responses

​Related Endpoints

Address Book

Portfolio

The bundle object

List Bundles

Endpoint

Example

Example Response

Create Bundle

Endpoint

Parameters

Example

Response

Get Bundle

Endpoint

Parameters

Example

Rename Bundle

Endpoint

Parameters

Example

Delete Bundle

Endpoint

Parameters

Example

Response

Add Address to Bundle

Endpoint

Parameters

Example

Response

Remove Address from Bundle

Endpoint

Parameters

Example

Response

Limits

Error Responses

Related Endpoints