Skip to main content

HTTP Provider Guide

Attest data from any HTTP/HTTPS endpoint.

Overview​

The HTTP provider is the most common way to attest data in L{CORE}. It fetches data from any HTTP endpoint and generates a zkTLS proof that the response came from the claimed server.

Basic Usage​

Simple GET Request​

import { LCore } from '@localecore/lcore-sdk'

const lcore = new LCore({
  attestorUrl: 'http://localhost:8001',
  cartesiUrl: 'http://localhost:10000',
  dappAddress: '0xAE0863401D5B953b89cad8a5E7c98f5136E9C26d',
})

const result = await lcore.attest({
  provider: 'http',
  params: {
    url: 'https://api.coingecko.com/api/v3/simple/price?ids=bitcoin&vs_currencies=usd'
  }
})

console.log('Claim ID:', result.claimId)

With Headers​

const result = await lcore.attest({
  provider: 'http',
  params: {
    url: 'https://api.example.com/user/profile',
    method: 'GET',
    headers: {
      'Authorization': 'Bearer your-api-token',
      'Accept': 'application/json'
    }
  }
})

POST Request​

const result = await lcore.attest({
  provider: 'http',
  params: {
    url: 'https://api.example.com/data',
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      query: 'user_balance',
      userId: '12345'
    })
  }
})

Privacy Buckets​

Bucketing Numeric Values​

const result = await lcore.attest({
  provider: 'http',
  params: {
    url: 'https://api.bank.com/accounts/balance',
    headers: { 'Authorization': 'Bearer token' }
  },
  bucketDefinition: {
    field: 'balance',
    boundaries: [0, 1000, 5000, 10000, 50000, 100000],
    labels: ['<1k', '1k-5k', '5k-10k', '10k-50k', '50k-100k', '>100k']
  }
})

// If balance is $7,500, stored bucket is "5k-10k"
console.log('Balance bucket:', result.bucket)

Multiple Buckets​

const result = await lcore.attest({
  provider: 'http',
  params: {
    url: 'https://api.portfolio.com/summary'
  },
  bucketDefinitions: {
    totalValue: {
      boundaries: [0, 10000, 100000, 1000000],
      labels: ['<10k', '10k-100k', '100k-1M', '>1M']
    },
    monthlyGain: {
      boundaries: [-20, -5, 0, 5, 20],
      labels: ['heavy-loss', 'loss', 'flat', 'gain', 'heavy-gain']
    }
  }
})

Response Redactions​

Redact Sensitive Fields​

Remove fields before storing:

const result = await lcore.attest({
  provider: 'http',
  params: {
    url: 'https://api.example.com/user',
    responseRedactions: [
      { jsonPath: 'ssn' },
      { jsonPath: 'address.street' },
      { jsonPath: 'creditCard.number' }
    ]
  }
})

Keep Only Specific Fields​

const result = await lcore.attest({
  provider: 'http',
  params: {
    url: 'https://api.example.com/user',
    responseKeep: [
      'userId',
      'verificationStatus',
      'accountAge'
    ]
  }
})

Encryption​

Full Response Encryption​

const result = await lcore.attest({
  provider: 'http',
  params: {
    url: 'https://api.example.com/sensitive-data',
    encrypt: true,
    encryptionKey: 'base64-nacl-public-key'
  }
})

// Data stored encrypted - only key holder can decrypt

Partial Encryption​

const result = await lcore.attest({
  provider: 'http',
  params: {
    url: 'https://api.example.com/user',
    encryptFields: ['ssn', 'dateOfBirth'],
    encryptionKey: 'base64-nacl-public-key'
  },
  bucketDefinition: {
    field: 'income',
    boundaries: [0, 50000, 100000],
    labels: ['<50k', '50k-100k', '>100k']
  }
})

// SSN encrypted, income bucketed

Advanced Options​

Timeout Configuration​

const result = await lcore.attest({
  provider: 'http',
  params: {
    url: 'https://slow-api.example.com/data',
    timeout: 30000  // 30 seconds
  }
})

Retry Configuration​

const result = await lcore.attest({
  provider: 'http',
  params: {
    url: 'https://flaky-api.example.com/data',
    retries: 3,
    retryDelay: 1000  // 1 second between retries
  }
})

Response Validation​

const result = await lcore.attest({
  provider: 'http',
  params: {
    url: 'https://api.example.com/status',
    validateResponse: {
      statusCode: 200,
      contentType: 'application/json',
      jsonSchema: {
        type: 'object',
        required: ['status', 'timestamp'],
        properties: {
          status: { type: 'string', enum: ['active', 'inactive'] },
          timestamp: { type: 'number' }
        }
      }
    }
  }
})

Common Patterns​

API with Pagination​

// Attest just the summary, not all pages
const result = await lcore.attest({
  provider: 'http',
  params: {
    url: 'https://api.example.com/transactions?limit=1&fields=total_count,total_amount'
  },
  bucketDefinition: {
    field: 'total_amount',
    boundaries: [0, 1000, 10000, 100000],
    labels: ['<1k', '1k-10k', '10k-100k', '>100k']
  }
})

OAuth-Protected API​

// First get OAuth token (not attested)
const tokenResponse = await fetch('https://auth.example.com/token', {
  method: 'POST',
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'your-client-id',
    client_secret: 'your-secret'
  })
})
const { access_token } = await tokenResponse.json()

// Then attest the protected endpoint
const result = await lcore.attest({
  provider: 'http',
  params: {
    url: 'https://api.example.com/protected/data',
    headers: {
      'Authorization': `Bearer ${access_token}`
    }
  }
})

GraphQL API​

const result = await lcore.attest({
  provider: 'http',
  params: {
    url: 'https://api.example.com/graphql',
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      query: `
        query GetUserBalance($id: ID!) {
          user(id: $id) {
            balance
            accountStatus
          }
        }
      `,
      variables: { id: 'user-123' }
    })
  },
  bucketDefinition: {
    field: 'data.user.balance',
    boundaries: [0, 1000, 10000],
    labels: ['low', 'medium', 'high']
  }
})

Error Handling​

try {
  const result = await lcore.attest({
    provider: 'http',
    params: { url: 'https://api.example.com/data' }
  })
} catch (error) {
  if (error.code === 'PROVIDER_UNAVAILABLE') {
    console.log('API is down, retry later')
  } else if (error.code === 'PROVIDER_AUTH_FAILED') {
    console.log('Check your API credentials')
  } else if (error.code === 'ZKTLS_PROOF_FAILED') {
    console.log('Could not verify TLS connection')
  } else {
    throw error
  }
}

Supported APIs​

The HTTP provider works with any API that:

  • Uses HTTPS (TLS 1.2 or higher)
  • Returns JSON responses
  • Has consistent response format

Known Compatible​

  • CoinGecko, CoinMarketCap (crypto prices)
  • Plaid, Yodlee (banking)
  • Stripe (payment data)
  • GitHub, GitLab (code metrics)
  • Twitter/X, LinkedIn (social data)
  • Most REST APIs

Known Limitations​

  • WebSocket-only APIs (use IoT provider)
  • APIs with certificate pinning
  • APIs requiring client certificates
  • Non-JSON responses (XML, binary)

Next Steps​