W3 Ledger MCP Server

Instructions

Implementation Reference

• src/tools.ts:402-405 (handler)

  The handler logic for create_gift_card, which performs a POST request to the /giftcard endpoint.

  case 'create_gift_card': {
      const res = await client.post('/giftcard', args);
      return toResult(res.data, !res.ok);
  }

• src/tools.ts:76-139 (schema)

  The JSON schema definition for the create_gift_card tool, including required inputs.

  {
      name: 'create_gift_card',
      description:
          'Create a gift card by debiting the customer\'s DAH balance. ' +
          'Requires dual signatures (customer + distribution). ' +
          'The card value is escrowed until the recipient claims it.',
      inputSchema: {
          type: 'object',
          properties: {
              customer_public_key: {
                  type: 'string',
                  description: 'Public key of the customer funding the gift card.',
              },
              customer_partyKey: {
                  type: 'string',
                  description: 'Party key identifying the customer.',
              },
              cardInfo: {
                  type: 'object',
                  description: 'Gift card details.',
                  properties: {
                      message: { type: 'string', description: 'Gift card message.' },
                      cardValue: {
                          type: 'number',
                          description: 'Value in DAH tokens (max 10,000).',
                          minimum: 0.01,
                          maximum: 10000,
                      },
                      selected_merchant: {
                          type: 'string',
                          description: 'Merchant the card is for.',
                      },
                      url: { type: 'string', description: 'Optional URL for the card.' },
                      customer_signature: {
                          type: 'string',
                          description: 'Customer\'s card signature.',
                      },
                  },
                  required: ['message', 'cardValue', 'selected_merchant'],
              },
              signature: {
                  type: 'string',
                  description: 'Customer transaction signature (EVM personal_sign).',
              },
              distributionSignature: {
                  type: 'string',
                  description: 'Distribution account co-signature for dual signing.',
              },
              timestamp: {
                  type: 'string',
                  description: 'ISO 8601 timestamp of the transaction.',
              },
          },
          required: [
              'customer_public_key',
              'customer_partyKey',
              'cardInfo',
              'signature',
              'distributionSignature',
              'timestamp',
          ],
      },
      access: 'write',
  },